Ettus Knowledge Base - User contributions [en]

Instructions for System Setup and Configuration

2026-04-27T06:44:48Z

NeelPandeya: /* Step 1: Install Xubuntu 24.04.3 */

==Introduction==

This document provides instructions for attendees to setup and configure their laptop or desktop computer system for use with the hands-on exercises and labs for the "USRP Open-Source Toolchain: UHD and GNU Radio" workshop/tutorial.

Note that all of this is optional. You only have to do this if you want to use the USRP in the workshop to do the hands-on exercises and actually use the USRP radio. If you do not want to do this and just watch the instructor's presentation, then you can skip all of this and just come to the workshop.

This document assumes that you are using a USRP B200/B210 radio, although the USRP X300/X310, N300, N310, N320, N321, X410 may be used.

In some sessions the radio will be provided to you; in other sessions you will need to provide your own radio. Check this with the organizer of your session.

Your laptop or desktop computer should be no more than around six or seven years old, with an Intel i5, i7, or i9 CPU or AMD equivalent and at least 4 cores, running at a 3.5 GHz clock speed or higher, with 8 GB memory, and at least one USB 3.0 port (for USRP B200/B210 radios) and one RJ-45 Ethernet port (for other USRP radios). You will need about 30 GB of free disk space for the Linux installation. You will need to have internet access during the entire installation, set-up, and configuration process.

==Step 1: Install Xubuntu 24.04.4==

Install Xubuntu 24.04.4. Note that you may instead install Ubuntu itself, or any other Ubuntu flavor such as Kubuntu, Lubuntu, Cinnamon, MATE, or Linux Mint. However, we recommend using Xubuntu because it is very light-weight, and the user interface is easy-to-use and intuitive, and it runs well on older or resource-constrained hardware. We have only tested with Ubuntu and Xubuntu.

https://ubuntu.com/desktop/flavors

Please install on-the-metal, and not in a Virtual Machine (VM). Please install specifically version 24.04.4.

If you already have an existing Windows or Linux installation on your computer, then you can install Ubuntu or Xubuntu alongside your already-existing operating system, in a dual-boot configuration. The installer will ask you about this, and it supports installing in a dual-boot configuration. However, note that there can be some challenges when dual-booting with Windows 11, and this may not be easy to set up and may not work well.

You can download the ISO images for Xubuntu from the links below. Whichever version you choose: Write the ISO image to a USB 3.0 drive, and boot from it, and install it. The USB drive capacity must be a minimum of 16 GB.

https://xubuntu.org/download/

https://cdimage.ubuntu.com/xubuntu/releases/noble/release/

==Step 2: Installation Settings==

During the Xubuntu installation process, set the username to be "ettus". This is not strictly necessary, but if you do this, then it will make all the commands in the installation instructions and in the exercises work more easily. The hostname does not matter. Do not use any disk encryption. Do not enable any volume management.

==Step 3: Apply Updates==

Once the installation is complete, boot into it, and open a terminal window, and apply updates. Run the commands listed below, in a terminal window.

sudo apt update
sudo apt upgrade

==Step 4: Install Dependencies==

Install the package dependencies for UHD, GNU Radio, and other tools. Run the commands listed below, in a terminal window.

sudo apt-get install openssh-server htop tree lshw meld git libfftw3-bin ncurses-bin libncurses6 libncursesw6 net-tools ethtool aptitude screen hwloc inxi wireshark wireshark-doc wireshark-dev tshark build-essential ntp doxygen gnome-disk-utility cpufrequtils libsndfile1-dev

sudo apt-get install autoconf automake build-essential ccache cmake cpufrequtils doxygen ethtool g++ git inetutils-tools libboost-all-dev libncurses6 libncurses-dev libusb-1.0-0 libusb-1.0-0-dev libusb-dev python3-dev python3-mako python3-numpy python3-requests python3-scipy python3-setuptools python3-ruamel.yaml

sudo apt-get install git cmake g++ libboost-all-dev libgmp-dev swig python3-numpy python3-mako python3-sphinx python3-lxml doxygen libfftw3-dev libsdl1.2-dev libgsl-dev libqwt-qt5-dev libqt5opengl5-dev python3-pyqt5 liblog4cpp5-dev libzmq3-dev python3-yaml python3-click python3-click-plugins python3-zmq python3-scipy python3-gi python3-gi-cairo gir1.2-gtk-3.0 libcodec2-dev libgsm1-dev libusb-1.0-0 libusb-1.0-0-dev libudev-dev python3-setuptools python3-pygccxml python3-thrift libqwt-qt5-6 libqwt-qt5-dev python3-pyqt5.qwt python3-qwt3d-qt5 libspdlog-dev libspdlog1.12 pybind11-dev python3-cppimport python3-pybind11 python3-pybindgen

==Step 5: Create a folder for GIT repositories==

Create a folder to hold all the GIT repositories. Run the commands listed below, in a terminal window.

mkdir $HOME/git

==Step 6: Create a work area folder==

Create a folder to hold workshop materials and for running exercises. Run the commands listed below, in a terminal window.

mkdir $HOME/workarea

==Step 7: Download the slides and materials==

Download the slides and materials for the workshop from the Ettus Knowledge Base (KB). Run the commands listed below, in a terminal window.

wget -P $HOME/workarea https://kb.ettus.com/images/a/ab/Workshop_GnuRadio_Materials_20171212.tar.gz
wget -P $HOME/workarea https://kb.ettus.com/images/f/fd/Workshop_GnuRadio_Slides_20250802.pdf

==Step 8: Unzip the materials==

Unzip the workshop materials file. Run the commands listed below, in a terminal window.

cd $HOME/workarea
tar zxvf Workshop_GnuRadio_Materials_20171212.tar.gz

==Step 9: Install UHD 4.9==

Install UHD version 4.9, and download all the USRP FPGA image files. Run the commands listed below, in a terminal window.

cd $HOME/git
git clone http://github.com/EttusResearch/uhd.git
cd uhd/host
mkdir build
cd build
git checkout v4.9.0.0
cmake ../
make -j4
sudo make install
sudo ldconfig
sudo uhd_images_downloader

==Step 10: Install VOLK 3.3.0==

Install the VOLK library. This used to be bundled with GNU Radio, but now it's broken out as a separate library. Run the commands listed below, in a terminal window.

cd $HOME/git
git clone --recursive https://github.com/gnuradio/volk.git
cd volk
mkdir build
cd build
git checkout v3.3.0
cmake -DCMAKE_BUILD_TYPE=Release -DPYTHON_EXECUTABLE=/usr/bin/python3 ../
make -j4
sudo make install
sudo ldconfig

==Step 11: Install GNU Radio 3.10.12==

Install GNU Radio version 3.10.12. Run the commands listed below, in a terminal window.

cd $HOME/git
git clone http://github.com/gnuradio/gnuradio.git
cd gnuradio
mkdir build
cd build
git checkout v3.10.12.0
cmake ../
make -j4
sudo make install
sudo ldconfig

==Step 12: Update the Bash RC shell file==

Add the following lines the end of your <code> $HOME/.bashrc </code> file. Use your preferred editor such as the graphical ones Gedit or Mousepad or a console-based text editor such as vi or emacs.

First, open the file using either the text editor.

mousepad $HOME/.bashrc
gedit $HOME/.bashrc
emacs $HOME/.bashrc

Next, add the two lines listed below to the very end of the file:

export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH
export PYTHONPATH=/usr/local/lib/python3.12/dist-packages:/usr/local/lib/python3.12/site-packages:$PYTHONPATH

Then, save the file, exit and close the text editor, exit and close the terminal window, and open a brand-new terminal window. Run the following command to verify that the PYTHONPATH variable is set:

python3 -c "import sys; print(sys.path)" | tr ',' '\n' | grep "\-packages"

and both of the paths above should be listed.

==Step 13: Apply the USB udev rules==

Apply the USB udev rules for the USRP B200/B210. If you are not using a USRP B200/B210, but some other Ethernet-based radio, then you can skip this step, although it is still good to do. Run the commands listed below, in a terminal window.

cd /usr/local/lib/uhd/utils
sudo cp uhd-usrp.rules /etc/udev/rules.d/
sudo udevadm control --reload-rules
sudo udevadm trigger

==Step 14: Install gr-osmosdr==

Install the gr-osmosdr Out-Of-Tree (OOT) module. Run the commands listed below, in a terminal window.

cd $HOME/git
git clone https://github.com/osmocom/gr-osmosdr
cd gr-osmosdr
mkdir build
cd build
cmake ../
make -j4
sudo make install
sudo ldconfig

==Step 15: Install gr-rds==

Install the gr-rds Out-Of-Tree (OOT) module. Run the commands listed below, in a terminal window.

cd $HOME/git
git clone https://github.com/bastibl/gr-rds
cd gr-rds
mkdir build
cd build
git checkout maint-3.10
cmake ../
make -j4
sudo make install
sudo ldconfig

==Step 16: Install GQRX==

Install GQRX. You will also need to install two more package dependencies. Run the commands listed below, in a terminal window.

sudo apt-get install libqt5svg5 libqt5svg5-dev
cd $HOME/git
git clone https://github.com/gqrx-sdr/gqrx
cd gqrx
mkdir build
cd build
git checkout v2.17.7
cmake ../
make -j4
sudo make install
sudo ldconfig

==Step 17: Install gr-paint==

Install gr-paint. Run the commands listed below, in a terminal window.

cd $HOME/git
git clone https://github.com/drmpeg/gr-paint
cd gr-paint
mkdir build
cd build
cmake ../
make -j4
sudo make install
sudo ldconfig

==Test the Installation==

If you did not see any errors in any of the previous steps, then your installation and configuration should now be complete. You can run a few simple and quick tests to verify that your system is running correctly and is ready for the workshop/tutorial.

First, run the commands below, even if you do not have any USRP radio connected to your computer.

uhd_find_devices
uhd_usrp_probe

You should see output similar to what is listed below when there is no USRP device connected.

ettus@lenovo-t480s:~$ uhd_find_devices
[INFO] [UHD] linux; GNU C++ version 13.3.0; Boost_108300; UHD_4.9.0.HEAD-0-g9ec1f582
No UHD Devices Found
ettus@lenovo-t480s:~$ uhd_usrp_probe
[INFO] [UHD] linux; GNU C++ version 13.3.0; Boost_108300; UHD_4.9.0.HEAD-0-g9ec1f582
Error: LookupError: KeyError: No devices found for ----->
Empty Device Address
ettus@lenovo-t480s:~$

You should see output similar to what is listed below when there is one USRP B200 device connected.

ettus@lenovo-t480s:~$ uhd_find_devices
[INFO] [UHD] linux; GNU C++ version 13.3.0; Boost_108300; UHD_4.9.0.HEAD-0-g9ec1f582
[INFO] [B200] Loading firmware image: /usr/local/share/uhd/images/usrp_b200_fw.hex...
--------------------------------------------------
-- UHD Device 0
--------------------------------------------------
Device Address:
serial: 3304B90
name: 4B200
product: B200
type: b200

ettus@lenovo-t480s:~$ uhd_usrp_probe
[INFO] [UHD] linux; GNU C++ version 13.3.0; Boost_108300; UHD_4.9.0.HEAD-0-g9ec1f582
[INFO] [B200] Detected Device: B200
[INFO] [B200] Loading FPGA image: /usr/local/share/uhd/images/usrp_b200_fpga.bin...
[INFO] [B200] Operating over USB 3.
[INFO] [B200] Detecting internal GPSDO....
[INFO] [GPS] No GPSDO found
[INFO] [B200] Initialize CODEC control...
[INFO] [B200] Initialize Radio control...
[INFO] [B200] Performing register loopback test...
[INFO] [B200] Register loopback test passed
[INFO] [B200] Setting master clock rate selection to 'automatic'.
[INFO] [B200] Asking for clock rate 16.000000 MHz...
[INFO] [B200] Actually got clock rate 16.000000 MHz.
_____________________________________________________
/
| Device: B-Series Device
| _____________________________________________________
| /
| | Mboard: B200
| | serial: 3304B90
| | name: 4B200
| | product: 1
| | revision: 5
| | FW Version: 8.0
| | FPGA Version: 16.0
| |
| | Time sources: none, internal, external, gpsdo
| | Clock sources: internal, external, gpsdo
| | Sensors: ref_locked
| | _____________________________________________________
| | /
| | | RX DSP: 0
| | |
| | | Freq range: -8.000 to 8.000 MHz
| | _____________________________________________________
| | /
| | | RX Dboard: A
| | | _____________________________________________________
| | | /
| | | | RX Frontend: A
| | | | Name: FE-RX1
| | | | Antennas: TX/RX, RX2
| | | | Sensors: temp, rssi, lo_locked
| | | | Freq range: 50.000 to 6000.000 MHz
| | | | Gain range PGA: 0.0 to 76.0 step 1.0 dB
| | | | Bandwidth range: 200000.0 to 56000000.0 step 0.0 Hz
| | | | Connection Type: IQ
| | | | Uses LO offset: No
| | | _____________________________________________________
| | | /
| | | | RX Codec: A
| | | | Name: B200 RX dual ADC
| | | | Gain Elements: None
| | _____________________________________________________
| | /
| | | TX DSP: 0
| | |
| | | Freq range: -8.000 to 8.000 MHz
| | _____________________________________________________
| | /
| | | TX Dboard: A
| | | _____________________________________________________
| | | /
| | | | TX Frontend: A
| | | | Name: FE-TX1
| | | | Antennas: TX/RX
| | | | Sensors: temp, lo_locked
| | | | Freq range: 50.000 to 6000.000 MHz
| | | | Gain range PGA: 0.0 to 89.8 step 0.2 dB
| | | | Bandwidth range: 200000.0 to 56000000.0 step 0.0 Hz
| | | | Connection Type: IQ
| | | | Uses LO offset: No
| | | _____________________________________________________
| | | /
| | | | TX Codec: A
| | | | Name: B200 TX dual DAC
| | | | Gain Elements: None

ettus@lenovo-t480s:~$

Second, you can run the GNU Radio Companion (GRC) tool. Run the commands below, and verify that the GRC window appears.

gnuradio-companion

Third, you can connect the USRP B200/B210 to the computer, and then run the command listed below.

lsusb

You should see the USRP listed in the output, as shown below.

ettus@lenovo-t480s:~$ lsusb
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 001 Device 004: ID 03f0:6a41 HP, Inc HP USB Optical Mouse
Bus 001 Device 005: ID 2500:0020 Ettus Research LLC USRP B210
Bus 002 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
Bus 002 Device 002: ID 0bda:0316 Realtek Semiconductor Corp. Card Reader
Bus 003 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 004 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
ettus@lenovo-t480s:~$

Fourth, you can run the command below, to confirm that GNU Radio is configured correctly, and that you are running the correct version.

ettus@lenovo-t480s:~$ gnuradio-config-info --print-all
/usr/local/
/usr/local/etc
/usr/local/etc/gnuradio/conf.d
/home/ettus/.config/gnuradio
/home/ettus/.local/state/gnuradio
Fri, 09 Jan 2026 14:37:15Z
testing-support;python-support;post-install;doxygen;man-pages;gnuradio-runtime;common-precompiled-headers;gr-ctrlport;gnuradio-companion;JSON/YAML config blocks;gr-blocks;gr-fec;gr-fft;gr-filter;gr-analog;gr-digital;gr-dtv;gr-audio;* alsa;* oss;gr-channels;gr-pdu;gr-qtgui;gr-trellis;gr-uhd;gr-uhd UHD 4.0 RFNoC;gr-utils;gr_modtool;gr_blocktool;gr-video-sdl;gr-vocoder;* codec2;* freedv;* gsm;gr-wavelet;gr-zeromq;gr-network
3.10.12.0
cc (Ubuntu 13.3.0-6ubuntu2~24.04) 13.3.0
Copyright (C) 2023 Free Software Foundation, Inc.
This is free software see the source for copying conditions. There is NO
warranty not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
c++ (Ubuntu 13.3.0-6ubuntu2~24.04) 13.3.0
Copyright (C) 2023 Free Software Foundation, Inc.
This is free software see the source for copying conditions. There is NO
warranty not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
/usr/bin/cc:::-O3 -DNDEBUG -fvisibility=hidden -Wsign-compare -Wall -Wno-uninitialized -Wignored-qualifiers -Wcast-qual
/usr/bin/c++:::-O3 -DNDEBUG -fvisibility=hidden -Wsign-compare -Wall -Wno-uninitialized -Wignored-qualifiers -Wcast-qual
2.11.1
ettus@lenovo-t480s:~$

==Conclusion==

If the simple tests of the installation listed above worked without any errors, then you are now finished, and you are now ready for the workshop/tutorial.

If you have any questions or problems, you can contact the author via email at <code> neel.pandeya@ettus.com </code>

We look forward to seeing you in the workshop/tutorial.

Power Monitoring for Energy Efficient 5G/6G with OAI and USRP

2025-11-19T11:47:55Z

NeelPandeya: Created page with "== Application Note Number and Authors == '''AN-844''' == Authors == Bharat Agarwal and Neel Pandeya ==Executive Summary== This Application Note will be published shortly..."

== Application Note Number and Authors ==

'''AN-844'''

== Authors ==

Bharat Agarwal and Neel Pandeya

==Executive Summary==

This Application Note will be published shortly.

[[Category:Application Notes]]

Knowledge Base

2025-11-08T17:16:09Z

NeelPandeya: /* Software Resources */

Welcome to the Ettus Research Knowledge Base (KB). The KB is continuously being updated and expanded. If you have any suggestions, or do not find what you are looking for, then please [http://www.ettus.com/contact Contact Us].
__NOTOC__
<div class="row">
<div class="col-1-3">
== [[Getting Started Guides|<i class="fa fa-road"></i> Getting Started Guides]] ==

'''Motherboards'''
* [[B200/B210/B200mini/B205mini/B206mini Getting Started Guides|B200/B210/B200mini/B205mini/B206mini]]
* [[Ettus USRP E300 Embedded Family Getting Started Guides|E310/E312/E313]]
* [[E320 Getting Started Guide|E320]]
* [[N200/N210 Getting Started Guides|N200/N210]]
* [[USRP N300/N310/N320/N321 Getting Started Guide|N300/N310/N320/N321]]
* [[X300/X310 Getting Started Guides|X300/X310]]
* [[USRP-2974 Getting Started Guide|USRP-2974]]
* [[USRP X410/X440 Getting Started Guide|X410/X440]]

'''Daughterboards'''
* [[OBX Getting Started Guides|OBX]]
* [[BasicTX/BasicRX Getting Started Guides|BasicTX/BasicRX]]
* [[CBX Getting Started Guides|CBX]]
* [[LFTX/LFRX Getting Started Guides|LFTX/LFRX]]
* [[SBX Getting Started Guides|SBX]]
* [[TwinRX Getting Started Guides|TwinRX]]
* [[UBX Getting Started Guides|UBX]]
* [[WBX Getting Started Guides|WBX]]

'''Other'''
* [[Getting_Started_with_RFNoC_in_UHD_4.0|RFNoC Development (UHD 4.x)]]
* [[RFNoC_4_Migration_Guide|RFNoC Migration Guide (UHD 3.x to UHD 4.x)]]
* [[Getting_Started_with_RFNoC_Development|RFNoC Development (UHD 3.x)]]
* [[Live SDR Environment Getting Started Guides|Live SDR Environment]]
* [[OctoClock CDA-2990 Getting Started Guides|OctoClock CDA-2990]]
* [[Using Ethernet-Based Synchronization on the USRP™ N3xx Devices|White Rabbit]]
* [[Getting Started with DPDK and UHD|DPDK]]

</div>
<div class="col-1-3">

== [[Hardware Resources|<i class="fa fa-cogs"></i> Hardware Resources]] ==
'''Motherboards'''
* [[B200/B210/B200mini/B205mini/B206mini]]
* [[Ettus USRP E300 Embedded Family Hardware Resources|E310/E312/E313]]
* [[E320|E320]]
* [[N200/N210]]
* [[N300/N310]]
* [[N320/N321]]
* [[X300/X310]]
* [[USRP-2974]]
* [[X410]]
* [[X440]]

'''Daughterboards'''
* [[OBX]]
* [[BasicTX/BasicRX]]
* [[CBX]]
* [[LFTX/LFRX]]
* [[SBX]]
* [[TwinRX]]
* [[UBX]]
* [[WBX]]

'''Other'''
* [[OctoClock CDA-2990]]
* [[GPSDO]]
* [[Antennas]]

</div>
<div class="col-1-3">

== [[Software Resources|<i class="fa fa-desktop"></i> Software Resources]] ==
'''Ettus Products'''
* [[UHD]]
* [[UHD Python API]]
* [[RFNoC|RFNoC (UHD 4.x)]]
* [[RFNoC (UHD 3.0)|RFNoC (UHD 3.x)]]

'''Third Party'''
* [[GNU Radio]]
* [[LabVIEW]]
* [[Matlab/Simulink]]
* [[OpenBTS]]
* [[Eurecom OpenAirInterface (OAI)]]
* [[srsLTE/srsUE]]
* [[Gqrx]]
* [[Fosphor]]

'''Reference Architectures'''
* [[Multichannel RF Reference Architecture]]
* [[OAI Reference Architecture for 5G and 6G Research with USRP]]
* [[5G OAI Neural Receiver Testbed with USRP X410]]
* [[AI-Based Spectrum Sensing with Nvidia Jetson and USRP]]
* [[5G OAI End-to-End Reference Architecture with USRP]]
* [[5G srsRAN End-to-End Reference Architecture with USRP]]

</div>
</div>

<div class="row">
<div class="col-1-3">

== [[UHD and USRP User Manual|<i class="fa fa-flag"></i> UHD and USRP User Manual]] ==

'''Software'''
* [https://files.ettus.com/manual/ UHD Manual (master)]
* [https://files.ettus.com/manual_archive/ UHD Manual Archive (previous releases)]

'''Motherboards'''
* [https://files.ettus.com/manual/page_usrp_b200.html B200/B210/B200mini/B205mini/B206mini]
* [https://files.ettus.com/manual/page_usrp_x3x0.html X300/X310]
* [https://files.ettus.com/manual/page_usrp2.html N200/N210]
* [https://files.ettus.com/manual/page_usrp_n3xx.html N300/N310/N320/N321]
* [https://files.ettus.com/manual/page_usrp_e3xx.html E310/E312/E313/E320]
* [https://files.ettus.com/manual/page_usrp_x4xx.html X410/X440]

'''Daughterboards'''
* [https://files.ettus.com/manual/page_dboards.html#dboards_basictx BasicRX/LFRX]
* [https://files.ettus.com/manual/page_dboards.html#dboards_basicrx BasicTX/LFTX]
* [https://files.ettus.com/manual/page_dboards.html#dboards_cbx CBX]
* [https://files.ettus.com/manual/page_dboards.html#dboards_sbx SBX]
* [https://files.ettus.com/manual/page_dboards.html#dboards_wbx WBX]
* [https://files.ettus.com/manual/page_dboards.html#dboards_ubx UBX]
* [https://files.ettus.com/manual/page_dboards.html#dboards_twinrx TwinRX]

'''Other'''
* [https://files.ettus.com/manual/page_octoclock.html OctoClock]

</div>
<div class="col-1-3">

== [[Application Notes|<i class="fa fa-file-text-o"></i> Application Notes]] ==
Application Notes (AN) and technical articles written by engineers, for engineers. These articles offer experienced analysis, design ideas, reference designs, and tutorials—to make you productive and successful using USRP devices.
</div>
<div class="col-1-3">

== [[Additional Resources|<i class="fa fa-book"></i> Additional Resources]] ==
* [[Workshop_Tutorial|Workshop/Tutorial]]
* [[Suggested Reading|Suggested Reading]]
* [[Suggested Videos|Suggested Videos]]
* [[CGRAN]]
* [[SDR Events]]
* [[GNU Radio Conference]]
* [[NEWSDR]]
* [[FOSDEM]]
* [[Cyberspectrum]]
</div>
</div>

<div class="row">
<div class="col-1-3">

== [[Technical Support|<i class="fa fa-life-ring"></i> Technical Support]] ==
* [[Email|Email]]
* [[Mailing Lists|Mailing Lists]]
* [[Matrix|GNU Radio Matrix Chat Server]]
* [[SDR_Boston_Slack|SDR Boston Slack Chat Server]]
* [[StackExchange|StackExchange]]
* [[NI_SRM|NI Service Request Manager (SRM)]]

</div>
<div class="col-1-3">

== [[Faq|<i class="fa fa-info-circle"></i> FAQ]] ==
* [[Technical FAQ|Technical]]
* [[Licensing FAQ|Licensing]]
* [[RFNoC_Frequently_Asked_Questions|RFNoC]]

</div>
<div class="col-1-3">

== [[Legacy Products| <i class="fa fa-hourglass-end"></i> Legacy Products]] ==
'''Motherboards'''
* [[USRP1|USRP1]]
* [[USRP2|USRP2]]
* [[E100/E110|E100/E110]]
* [[B100]]

'''Daughterboards'''
* [[DBSRX2]]
* [[TVRX2]]
* [[XCVR2450]]

5G OAI End-to-End Reference Architecture with USRP

2025-11-07T22:12:45Z

NeelPandeya:

== 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 (MCX631102A-ACAT) 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 (MCX631102A-ACAT)
** Dual-port SFP28, PCIe Gen 4, Linux + DPDK compatible
** [https://www.nvidia.com/en-us/networking/products/ethernet-adapters/connectx-6-lx/ Product Page (NVIDIA)]
** [https://www.amazon.com/NVIDIA-MCX631102A-ACAT-ConnectX-6-Dual-Port/dp/B09H3FWDVM/ Amazon 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]]

5G OAI End-to-End Reference Architecture with USRP

2025-11-07T22:12:08Z

NeelPandeya:

== 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 (MCX631102A-ACAT) 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 (MCX631102A-ACAT)
** Dual-port SFP28, PCIe Gen 4, Linux + DPDK compatible
** [https://www.nvidia.com/en-us/networking/products/ethernet-adapters/connectx-6-lx/ Product Page (NVIDIA)]
** [https://www.amazon.com/NVIDIA-MCX631102A-ACAT-ConnectX-6-Dual-Port/dp/B09H3FWDVM/ Amazon 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|800px|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]]

5G OAI End-to-End Reference Architecture with USRP

2025-11-07T22:10:36Z

NeelPandeya:

== 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 (MCX631102A-ACAT) 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 (MCX631102A-ACAT)
** Dual-port SFP28, PCIe Gen 4, Linux + DPDK compatible
** [https://www.nvidia.com/en-us/networking/products/ethernet-adapters/connectx-6-lx/ Product Page (NVIDIA)]
** [https://www.amazon.com/NVIDIA-MCX631102A-ACAT-ConnectX-6-Dual-Port/dp/B09H3FWDVM/ Amazon 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|50%|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].

mmm
mmm
mmm

[[Category:Application Notes]]

File:multi ue connection.png

2025-11-07T22:10:21Z

NeelPandeya: NeelPandeya uploaded a new version of File:multi ue connection.png

File:multi ue connection.png

2025-11-07T22:07:51Z

NeelPandeya:

File:Double UE connection on gnb logs.png

2025-11-07T22:07:28Z

NeelPandeya:

File:double ue connection on wireshark.png

2025-11-07T22:06:58Z

NeelPandeya:

File:mobile phone connectivity.png

2025-11-07T22:06:35Z

NeelPandeya:

File:Open Cell Sim Card.jpg

2025-11-07T22:06:14Z

NeelPandeya:

5G OAI End-to-End Reference Architecture with USRP

2025-11-07T22:05:20Z

NeelPandeya:

== 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 (MCX631102A-ACAT) 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 (MCX631102A-ACAT)
** Dual-port SFP28, PCIe Gen 4, Linux + DPDK compatible
** [https://www.nvidia.com/en-us/networking/products/ethernet-adapters/connectx-6-lx/ Product Page (NVIDIA)]
** [https://www.amazon.com/NVIDIA-MCX631102A-ACAT-ConnectX-6-Dual-Port/dp/B09H3FWDVM/ Amazon 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|50%|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].

mmm
mmm

[[Category:Application Notes]]

File:Wireshark Packet Captures.png

2025-11-07T22:05:01Z

NeelPandeya:

File:OAI UE Config file.png

2025-11-07T22:04:30Z

NeelPandeya:

File:ORU Update.png

2025-11-07T22:03:56Z

NeelPandeya:

File:AMF IP Address.png

2025-11-07T22:03:20Z

NeelPandeya:

5G OAI End-to-End Reference Architecture with USRP

2025-11-07T22:02:50Z

NeelPandeya:

== 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 (MCX631102A-ACAT) 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 (MCX631102A-ACAT)
** Dual-port SFP28, PCIe Gen 4, Linux + DPDK compatible
** [https://www.nvidia.com/en-us/networking/products/ethernet-adapters/connectx-6-lx/ Product Page (NVIDIA)]
** [https://www.amazon.com/NVIDIA-MCX631102A-ACAT-ConnectX-6-Dual-Port/dp/B09H3FWDVM/ Amazon 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|50%|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].

mmm

[[Category:Application Notes]]

File:MCC MNC update.png

2025-11-07T22:02:25Z

NeelPandeya:

5G OAI End-to-End Reference Architecture with USRP

2025-11-07T22:01:11Z

NeelPandeya:

== 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 (MCX631102A-ACAT) 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 (MCX631102A-ACAT)
** Dual-port SFP28, PCIe Gen 4, Linux + DPDK compatible
** [https://www.nvidia.com/en-us/networking/products/ethernet-adapters/connectx-6-lx/ Product Page (NVIDIA)]
** [https://www.amazon.com/NVIDIA-MCX631102A-ACAT-ConnectX-6-Dual-Port/dp/B09H3FWDVM/ Amazon 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|50%|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]]

File:OAI With Google Pixel 9.jpg

2025-11-07T21:58:14Z

NeelPandeya:

File:cable setup with USRP UE.png

2025-11-07T21:57:48Z

NeelPandeya:

5G OAI End-to-End Reference Architecture with USRP

2025-11-07T21:57:18Z

NeelPandeya:

== 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 (MCX631102A-ACAT) 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 (MCX631102A-ACAT)
** Dual-port SFP28, PCIe Gen 4, Linux + DPDK compatible
** [https://www.nvidia.com/en-us/networking/products/ethernet-adapters/connectx-6-lx/ Product Page (NVIDIA)]
** [https://www.amazon.com/NVIDIA-MCX631102A-ACAT-ConnectX-6-Dual-Port/dp/B09H3FWDVM/ Amazon 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:OAI-E2E/Images/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:OAI-E2E/Images/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:OAI-E2E/Images/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:OAI-E2E/Images/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-E2E/Images/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:OAI-E2E/Images/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:OAI-E2E/Images/Open_Cell_Sim_Card.jpg|center|50%|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].

mmm
mmm

[[Category:Application Notes]]

File:cable setup with COTS UE.png

2025-11-07T21:56:55Z

NeelPandeya:

5G OAI End-to-End Reference Architecture with USRP

2025-11-07T21:56:22Z

NeelPandeya:

== 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 (MCX631102A-ACAT) 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 (MCX631102A-ACAT)
** Dual-port SFP28, PCIe Gen 4, Linux + DPDK compatible
** [https://www.nvidia.com/en-us/networking/products/ethernet-adapters/connectx-6-lx/ Product Page (NVIDIA)]
** [https://www.amazon.com/NVIDIA-MCX631102A-ACAT-ConnectX-6-Dual-Port/dp/B09H3FWDVM/ Amazon 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:OAI-E2E/Images/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:OAI-E2E/Images/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:OAI-E2E/Images/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:OAI-E2E/Images/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-E2E/Images/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:OAI-E2E/Images/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:OAI-E2E/Images/Open_Cell_Sim_Card.jpg|center|50%|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].

mmm

[[Category:Application Notes]]

File:OAI E2E Arch.jpg

2025-11-07T21:55:51Z

NeelPandeya:

File:OAI E2E Arch Different Machines.jpg

2025-11-07T21:55:07Z

NeelPandeya:

5G OAI End-to-End Reference Architecture with USRP

2025-11-07T21:54:00Z

NeelPandeya:

== 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 (MCX631102A-ACAT) 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 (MCX631102A-ACAT)
** Dual-port SFP28, PCIe Gen 4, Linux + DPDK compatible
** [https://www.nvidia.com/en-us/networking/products/ethernet-adapters/connectx-6-lx/ Product Page (NVIDIA)]
** [https://www.amazon.com/NVIDIA-MCX631102A-ACAT-ConnectX-6-Dual-Port/dp/B09H3FWDVM/ Amazon 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:OAI-E2E/Images/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:OAI-E2E/Images/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:OAI-E2E/Images/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:OAI-E2E/Images/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-E2E/Images/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:OAI-E2E/Images/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:OAI-E2E/Images/Open_Cell_Sim_Card.jpg|center|50%|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]]

5G OAI End-to-End Reference Architecture with USRP

2025-11-07T21:53:04Z

NeelPandeya:

== 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 (MCX631102A-ACAT) 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 (MCX631102A-ACAT)
** Dual-port SFP28, PCIe Gen 4, Linux + DPDK compatible
** [https://www.nvidia.com/en-us/networking/products/ethernet-adapters/connectx-6-lx/ Product Page (NVIDIA)]
** [https://www.amazon.com/NVIDIA-MCX631102A-ACAT-ConnectX-6-Dual-Port/dp/B09H3FWDVM/ Amazon 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:OAI-E2E/Images/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:OAI-E2E/Images/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:OAI-E2E/Images/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:OAI-E2E/Images/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-E2E/Images/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:OAI-E2E/Images/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:OAI-E2E/Images/Open_Cell_Sim_Card.jpg|center|50%|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

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]]

5G OAI End-to-End Reference Architecture with USRP

2025-11-07T18:23:30Z

NeelPandeya:

5G OAI End-to-End Reference Architecture with USRP

2025-11-07T18:17:20Z

NeelPandeya:

5G OAI End-to-End Reference Architecture with USRP

2025-11-07T18:14:10Z

NeelPandeya:

5G OAI End-to-End Reference Architecture with USRP

2025-11-07T17:06:28Z

NeelPandeya:

5G OAI End-to-End Reference Architecture with USRP

2025-11-07T16:44:12Z

NeelPandeya:

5G OAI End-to-End Reference Architecture with USRP

2025-11-07T16:22:19Z

NeelPandeya:

5G OAI End-to-End Reference Architecture with USRP

2025-11-07T16:21:50Z

NeelPandeya:

5G OAI End-to-End Reference Architecture with USRP

2025-11-07T16:05:20Z

NeelPandeya:

5G OAI End-to-End Reference Architecture with USRP

2025-11-07T16:02:33Z

NeelPandeya:

5G OAI End-to-End Reference Architecture with USRP

2025-11-07T15:49:06Z

NeelPandeya:

5G OAI End-to-End Reference Architecture with USRP

2025-11-07T15:48:10Z

NeelPandeya:

5G OAI End-to-End Reference Architecture with USRP

2025-11-07T15:46:18Z

NeelPandeya:

5G OAI End-to-End Reference Architecture with USRP

2025-11-07T15:36:32Z

NeelPandeya: Created page with "== Application Note Number and Authors == '''AN-598''' == Authors == Bharat Agarwal and Neel Pandeya ==Executive Summary== This Application Note presents a comprehensive..."

File:srsran pixel9 50pc.png

2025-11-07T13:58:05Z

NeelPandeya:

5G srsRAN End-to-End Reference Architecture with USRP

2025-11-07T13:56:55Z

NeelPandeya: /* Commercial UE Setup: Google Pixel 9 Over-the-Air (OTA) */

== Application Note Number and Authors ==

'''AN-599'''

== Authors ==

Bharat Agarwal and Neel Pandeya

== Executive Summary ==

This Application Note presents a comprehensive reference design for deploying 5G NR Standalone (SA) systems using a hybrid open-source software stack: the srsRAN radio access network components and the OpenAirInterface (OAI) Core Network.
This setup runs on NI/Ettus USRP radios, including the B210, enabling practical, low-cost, end-to-end 5G experimentation.

This configuration supports full 5G SA mode and enables complete end-to-end evaluation of the entire protocol stack, from the physical layer up to the core network.

=== Core Network Deployment Options ===
The OAI Core Network can be deployed in two modes:

* Single-machine deployment: CN and gNB run on the same machine — ideal for compact or portable test setups.
* Multi-machine deployment: CN is hosted on a separate machine — ideal for performance scaling or distributed 5G architecture evaluation.

=== UE Configuration Options ===
This reference architecture supports the following UE configurations:

* A software-defined UE implemented using '''srsUE''' with a USRP B210.
* A modem-based UE, such as Quectel or Sierra Wireless modules.
* A COTS 5G handset (e.g., '''Google Pixel 9''') for interoperability and benchmarking.

== Overview of the OpenAirInterface (OAI) Software Stack ==

The OAI) software provides a fully open-source and standards-compliant implementation of the 3GPP 5G New Radio (NR) 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) — a non-profit organization that promotes open wireless innovation and collaborative research.

OAI enables complete 5G system prototyping and research with implementations of:
* The gNB (next-generation base station)
* The UE (user equipment)
* The 5G Core Network (5GCN)

The OAI 5G NR stack is designed to:
* Operate in real time with USRP radios
* Support interoperability with commercial 5G NR handsets (e.g., COTS devices)
* Enable academic, experimental, and pre-commercial deployments

The OAI software stack is organized into multiple Git repositories, allowing modularity and collaborative development:

* OAI 5G Radio Access Network (RAN) Project:
[https://gitlab.eurecom.fr/oai/openairinterface5g gitlab.eurecom.fr/oai/openairinterface5g]

* OAI 5G Core Network (OAI-CN):
[https://gitlab.eurecom.fr/oai/cn5g gitlab.eurecom.fr/oai/cn5g]

OAI source code is freely available for non-commercial and academic research use.
Licensing details and additional documentation are available on the [https://www.openairinterface.org/ OpenAirInterface website].

== Overview of srsRAN ==

srsRAN (Software Radio Systems Radio Access Network) is an open-source 4G and 5G software suite developed by Software Radio Systems Ltd. (SRS).
It enables researchers, developers, and network engineers to deploy and experiment with end-to-end wireless communication systems.
The suite provides modular components for building complete Radio Access Networks (RANs) and supports both 4G LTE and 5G NR (New Radio).

=== Key Components of srsRAN 5G ===
The srsRAN 5G stack is composed of several main components:

* srsRAN gNB: Implements the 5G NR base station (gNodeB), including PHY, MAC, RLC, PDCP, and NGAP layers. Supports standalone (SA) mode and connects to a 5G Core Network via NG interfaces.
* srsUE: A 4G LTE software user equipment used primarily for legacy LTE research. The 5G UE is under active development and partially supported.
* srsEPC (for LTE): The Evolved Packet Core for 4G LTE deployments. In 5G, this is replaced by external 5G Core Network solutions such as OAI-CN5G or commercial alternatives.
* srsGUI and nrscope: Tools for real-time visualization and debugging of signal and protocol layer performance.

=== Supported Features ===
* 5G NR Standalone (SA) mode operation (Release 15+)
* Configurable numerology, bandwidth, and frame structure
* Support for USRP hardware (e.g., B210, N3xx, X410)
* Dynamic scheduling, HARQ, and experimental beamforming
* Compatibility with open-source 5G Core solutions (e.g., OAI-CN5G)

=== Use Cases ===
srsRAN is widely used for:
* Academic research and prototyping
* 5G network testing and benchmarking
* Private network deployments
* SDR-based teaching and training environments

=== Licensing and Community ===
srsRAN is released under the AGPLv3 license, making it freely available for modification and redistribution under open-source terms.
The project is actively maintained and supported by a growing developer community on platforms such as [https://github.com/srsran GitHub] and [https://gitlab.com/srsran GitLab].

Overall, srsRAN provides a robust and flexible platform for 4G/5G experimentation and serves as a valuable resource for researchers working in wireless communications.

== Overview of the Reference Architecture ==

The OAI USRP Reference Architecture enables researchers, developers, and system integrators to build complete 5G NR systems using open-source software and commercial SDR 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 User Equipment (UE), including Quectel 5G modules, USRP-based UEs, and commercial handsets such as the Google Pixel 9 with an open SIM.

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

In this setup, both the OAI Core Network (CN) and the OAI NR gNB are hosted on the same physical machine.
This configuration is typically used for:

* Lab-based research and teaching environments
* Portable demos and proof-of-concept systems
* Quick-start testbeds for 5G protocol stack development

Architecture Highlights:
* Compute Node: High-core-count x86 server (e.g., Intel Xeon w7-2495X, 24 cores)
* Operating System: Ubuntu 22.04
* Software Stack: OpenAirInterface gNB (monolithic) and 5G Core (AMF, SMF, UPF, NRF, etc.)
* UHD Version: 4.8
* RF Front-End: USRP X410 with SFP+ (10/100 Gbps) link

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

Limitations:
* Less suitable for high-throughput traffic testing
* Shared CPU and I/O resources may limit performance

[[File:srsgnb_srsue_oaiue_50pc.jpg|center|800px|thumb|Single-host deployment where both the OAI Core Network and the srsRAN gNB are executed on the same machine. RF connectivity is established using a USRP B210, enabling communication with the gNB and various types of UEs, including Quectel modules and the Google Pixel 9.]]

=== Deployment 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
* Scalable testbeds with high-throughput and isolated workloads
* Large MIMO, beamforming, or MEC-based deployments

Architecture Highlights:
* gNB Node: Intel Xeon w7-2495X, 24 cores, Ubuntu 22.04
* CN Node: Separate x86 server, also running Ubuntu 22.04
* Interconnect: High-speed Ethernet via managed switch
* RF Front-End: USRP X410 with dual SFP+ for IQ data

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

Considerations:
* Requires correct IP addressing, routing, and DNS setup
* More complex to configure and monitor

[[File:srsgnb_srsue_oaiue_separate_50pc.jpg|center|thumb|800px|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 Setup ===

The diagram in Figure [[#fig_quectel_cable|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 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 (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 a safe operating range.
* Downstream RF Splitting: The combined RF signal is routed to a 2-way splitter (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/25 G) links for baseband data transfer and synchronization.

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

=== USRP-Based srsUE Cable Setup ===

Figure [[#fig_usrp_cable|below]] illustrates the RF cabling setup used when both the srsRAN gNB and srsUE are implemented using separate USRP X410 and B210 devices.
This setup enables full bidirectional communication in a lab environment without the need for over-the-air (OTA) transmission.

* Dual SFP+ Connection: Each USRP is connected to its respective host PC via dual SFP+ ports (Port 0 and Port 1) and USB 3.0, 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. Within operational range for the 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.

=== USRP-Based OAI-UE Cable Setup ===

A similar RF cabling setup applies when both the srsRAN gNB and OAI-UE are implemented using separate USRP B210 devices.
This configuration also enables full bidirectional communication in a lab environment without OTA transmission.

* USB 3.0 Connection: Each USRP B210 is connected to its respective host PC via USB 3.0, 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: A fixed 40 dB attenuator is inserted before the splitter connecting to the UE-side USRP.
* Bidirectional Lab Setup: The cable-based signal path ensures controlled, interference-free bidirectional testing.

[[File:srsue_oaueonly.png|center|900px|thumb|Cable setup between srsRAN gNB and srsUE or OAI-UE using USRP X410, B210 devices and RF splitters.]]

=== Commercial UE Setup: Google Pixel 9 Over-the-Air (OTA) ===

Figure [[#fig_pixel9_ota|below]] illustrates the setup for using a commercial 5G smartphone (Google Pixel 9) as the UE in conjunction with the srsRAN 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 processor (24 cores, 2.5 GHz) and interfaces with a USRP X410 via two SFP+ ports.
* OTA Link: The RF connection between the USRP and the Pixel 9 is established over the air, eliminating the need for RF splitters or coaxial cabling.
* SIM Card: The 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:srsran_pixel9__50pc.png|center|900px|thumb|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 provided 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 co-locate or distribute gNB and Core Network (CN) components and switch between different UE types depending on the research focus (PHY-level tuning, link testing, or full-stack validation).

=== Hardware Components ===

* Three or Two Desktop Computers:
Intel Core i9 CPU (10th–12th Gen) @ ≥4.0 GHz, with ≥10 physical cores and NVMe disk drives.
(See the Hardware Requirements section for further details.)

* Two 10 Gbps Ethernet Network Cards:
* Recommended: Intel 810-XXVDA2
* Recommended: NVIDIA/Mellanox ConnectX-6 Lx (MCX631102A-ACAT)

* Two USRP Devices:
The gNB and UE each require one USRP. Supported devices include N300, N310, N320, N321, and X410.
Mixed configurations are also supported (e.g., X410 for gNB and N310 for UE).

* USRP X410: High-performance, 4 TX/RX channels, suitable for advanced 5G/6G R&D.
[https://kb.ettus.com/X410 Documentation] | [https://www.ettus.com/all-products/usrp-x410/ Product Page]

* USRP N320 / N321: Wideband 2 TX/RX MIMO SDR with high dynamic range and onboard GPSDO (N321 only).
[https://kb.ettus.com/N320/N321 Documentation] | [https://www.ettus.com/all-products/usrp-n320/ N320 Product] | [https://www.ettus.com/all-products/usrp-n321/ N321 Product]

* USRP N300 / N310: Compact 4-channel SDR supporting distributed systems.
[https://kb.ettus.com/N300/N310 Documentation] | [https://www.ettus.com/all-products/usrp-n300/ N300 Product] | [https://www.ettus.com/all-products/usrp-n310/ N310 Product]

* One QSFP28-to-SFP28 Breakout Cable (required for 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] – 100 GbE to 4×25 GbE, 3 m, 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] – 100 GbE to 4×25 GbE, 3 m, 30 AWG

* One OctoClock-G:
Provides synchronization for gNB and UE USRPs.
Must be the “-G” model (with GPSDO).
* [https://kb.ettus.com/OctoClock_CDA-2990 Ettus KB – OctoClock CDA-2990]
* [https://www.ettus.com/all-products/octoclock-g/ Product Page]

* Four 10 Gbps Ethernet Cables with SFP+ terminations:
Required for N3xx and N32x devices; not needed for X410.
* [https://www.ettus.com/all-products/10gige-dc/ DAC Cable Listing]
* [https://www.ettus.com/all-products/10gige-1m/ 1 m SFP+ DAC]
* [https://www.ettus.com/all-products/10gige-3m/ 3 m SFP+ DAC]

* Four VERT900 and/or VERT2450 Antennas:
* [https://www.ettus.com/all-products/vert900/ VERT900 (824–960 MHz)]
* [https://www.ettus.com/all-products/vert2450/ VERT2450 (2.4–2.5 GHz / 4.9–5.9 GHz)]

* One Quectel RM500Q-GL 5G Wireless Modem Module:
Used as a UE option in the reference architecture.
* [https://www.quectel.com/5g-iot-modules/ Quectel 5G Modules]
* [https://www.quectel.com/product/5g-rm520n-series/ RM520N Series]

* One Google Pixel 9 5G Handset:
Used as a COTS UE; ensure it is unlocked.
* [https://www.gsmarena.com/ GSMArena Specs]
* [https://www.amazon.com/ Amazon Listing]

* Two 5G SIM Cards + One USB UICC/SIM Reader-Writer:
* [https://open-cells.com/index.php/sim-cards/ Open Cells – SIM Cards]

* One Mini-Circuits 4-way DC-Pass SMA Splitter (ZN4PD1-63HP-S+): 250–6000 MHz / 50 Ω
* [https://www.minicircuits.com/WebStore/Splitters.html Splitters Catalog]
* [https://www.minicircuits.com/WebStore/dashboard.html?model=ZN4PD1-63HP-S%2B Product Page]

* Two Mini-Circuits 2-way DC-Pass SMA Splitters (ZN2PD2-50-S+): 500–5000 MHz / 50 Ω
* [https://www.minicircuits.com/WebStore/Splitters.html Splitters Catalog]
* [https://www.minicircuits.com/WebStore/dashboard.html?model=ZN2PD2-50-S%2B Product Page]

* Four Mini-Circuits VAT-10+ Attenuators (10 dB, DC–6000 MHz, 50 Ω):
* [https://www.minicircuits.com/WebStore/dashboard.html?model=VAT-10%2B Product Page]

* Four Mini-Circuits VAT-20+ Attenuators (20 dB, DC–6000 MHz, 50 Ω):
* [https://www.minicircuits.com/WebStore/dashboard.html?model=VAT-20%2B Product Page]

* Four Mini-Circuits VAT-30+ Attenuators (30 dB, DC–6000 MHz, 50 Ω):
* [https://www.minicircuits.com/WebStore/dashboard.html?model=VAT-30%2B Product Page]

* Fourteen Mini-Circuits Hand-Flex SMA Coax Cables (086-36SM+, 36", 18 GHz):
* [https://www.minicircuits.com/WebStore/dashboard.html?model=086-36SM%2B Product Page]
* [https://www.minicircuits.com/pdfs/086-36SM+.pdf Datasheet PDF]

* One NETGEAR GS108 8-Port Gigabit Ethernet Switch:
* [https://www.netgear.com/business/wired/switches/unmanaged/gs108/ Product Page]
* [https://www.amazon.com/NETGEAR-Ethernet-Unmanaged-Lifetime-Protection/dp/B00MPVR50A/ Amazon Listing]

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

== Hardware Requirements ==

=== Host Computers ===
Three or two host computers are needed — one for the gNB, one for the UE, and one for the CN — with the specifications discussed in this section. The requirements for the host running the CN are not as high as for the gNB and UE, but it is recommended that all three hosts meet the requirements described here. It is also strongly recommended that each of the gNB, UE, and CN be implemented on their own dedicated system. A single host computer should only run the gNB, or the UE, or the CN.

=== CPU ===
* We recommend using an Intel Core i9 or Intel Xeon CPU from the 10<sup>th</sup>, 11<sup>th</sup>, or 12<sup>th</sup> Generation, with:
** Minimum clock speed of 4.0 GHz
** Minimum 10 physical cores
** At least 40 PCIe lanes (or enough to support GPU and 10 Gbps Ethernet)
** PCIe Gen 4 support (preferred)
* Recommended examples include:
** [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 physical cores, up to 4.60 GHz, 10<sup>th</sup> Gen
** [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 physical cores, up to 5.20 GHz, 12<sup>th</sup> Gen
** Intel Xeon Platinum 8351N

=== Disk ===
* We strongly recommend using only NVMe SSDs, ideally with a PCIe Gen-4 interface for maximum throughput.
* Do not use SATA disks — they are not sufficient for the data rates required in this application.
* Recommended model:
** [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/ Samsung 980 PRO on Amazon]
** [https://www.tomshardware.com/reviews/samsung-980-pro-m-2-nvme-ssd-review Tom’s Hardware Review of Samsung 980 PRO]
* RAID configurations with multiple NVMe drives are generally not required, but can be explored to further enhance throughput.

=== Memory ===
The system should have either dual-channel or quad-channel DDR4 or DDR5 (preferred) memory, with the highest clock speed available. A minimum of 16 GB or 32 GB should be sufficient. Larger amounts of memory are typically unnecessary, as no virtualization, RAM disk, or other large in-memory buffering is being used.

=== GPU ===
The GPU does not matter for the purposes of running UHD and OAI. If you plan to perform AI/ML processing on the GPU, select an appropriate accelerator. The OAI 5G stack does not currently leverage the GPU.

=== 10 Gbps Ethernet Network Card ===
* Both the gNB and UE systems require a two-port 10 Gbps Ethernet network card for connecting to the USRP radios.
* The Core Network (CN) system does not interface with USRPs directly and therefore does not require a 10G NIC.
* Ensure the computer chassis has adequate space and airflow to accommodate the network card.
* Recommended options:
** Intel E810-XXVDA2 (25GbE capable, backward compatible with 10GbE) — Works well with Ubuntu 20.04+ and supports DPDK. Ideal for advanced research requiring high throughput.
*** [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]
** '''NVIDIA ConnectX-6 Lx (MCX631102A-ACAT)''' — Dual-port SFP28, PCIe Gen4, excellent compatibility with Linux and DPDK.
*** [https://www.nvidia.com/en-us/networking/products/ethernet-adapters/connectx-6-lx/ Product Page (NVIDIA)]
*** [https://www.amazon.com/NVIDIA-MCX631102A-ACAT-ConnectX-6-Dual-Port/dp/B09H3FWDVM/ Amazon]

=== QSFP28-to-SFP28 Breakout Cable for USRP X410 ===
The USRP X410 features a QSFP28 port (100 Gbps Ethernet). To interface with a host computer equipped with 10 Gbps Ethernet, a QSFP28-to-SFP28 breakout cable is required. This is essential for X410 deployments, but is not necessary for USRP N300, N310, N320, or N321 devices.

Recommended Breakout Cables:
* [https://store.nvidia.com/en-us/networking/store/product/MCP7F00-A003R26N/nvidiamcp7f00-a003r26ndacsplittercableethernet100gbeto4x25gbe3m/ NVIDIA MCP7F00-A003R26N] – 100 GbE to 4×25 GbE, 3 m, 26 AWG
* [https://store.nvidia.com/en-us/networking/store/product/MCP7F00-A003R30L/nvidiamcp7f00-a003r30ldacsplittercableethernet100gbeto4x25gbe3m/ NVIDIA MCP7F00-A003R30L] – 100 GbE to 4×25 GbE, 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] – 100 GbE to 4×25 GbE, 1 m, 30 AWG

Alternative: Direct 100 Gbps Connection to Host
Direct connectivity to the 100 Gbps QSFP28 port is possible using a compatible 100 GbE NIC. Recommended options:
* [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 NVIDIA Mellanox MCX516A-CCAT] – ConnectX-5 EN, PCIe Gen3
* [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 NVIDIA Mellanox MCX516A-CDAT] – ConnectX-5 Ex, PCIe Gen4
* [https://store.mellanox.com/products/nvidia-mcp1600-c003e26n-passive-copper-cable-ethernet-100gbe-qsfp28-3m-black-26awg-ca-n.html NVIDIA MCP1600-C003E26N] – 100 GbE QSFP28, 3 m, 26 AWG
* [https://store.mellanox.com/products/nvidia-mcp1600-c003e30l-passive-copper-cable-ethernet-100gbe-qsfp28-3m-black-30awg-ca-l.html NVIDIA MCP1600-C003E30L] – 100 GbE QSFP28, 3 m, 30 AWG

Intel Alternative:
* [https://ark.intel.com/content/www/us/en/ark/products/series/184846/100gbe-intel-ethernet-network-adapter-e810.html Intel E810 Series (QSFP28 and SFP28 cards)]

Note: This reference architecture release does not yet require full 100 Gbps Ethernet. The dual 10 Gbps configuration is sufficient unless testing FR2 200/400 MHz bandwidth or 2×2 MIMO.

Example Host Systems:
* [https://system76.com/desktops/thelio-mira-b2/configure System76 Thelio Mira]
* [https://www.dell.com/en-us/work/shop/desktops-all-in-one-pcs/precision-5820-tower-workstation/spd/precision-5820-workstation Dell Precision 5820]

=== USRP Devices ===
Two USRP devices are required: one for the gNB and one for the UE. The devices can be any combination of the following:
* 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]

These devices are fully interchangeable across the gNB and UE systems. For instance, the gNB may use a USRP X410, while the UE may use a USRP N310.

Supported Bandwidths:
* FR1 (Sub-6 GHz): All listed USRP models support up to 100 MHz channel bandwidths.
* FR2 (mmWave):
** USRP N320: Supports 50, 100, 200 MHz
** USRP X410: Supports 50, 100, 200, 400 MHz

=== OctoClock-G ===
One OctoClock-G device is required to synchronize the gNB USRP and the UE USRP.
* Ensure the device is the “-G” model, which includes an internal GPSDO (GPS Disciplined Oscillator) module.
* This synchronization device is only necessary when the UE is implemented using a USRP radio.

More Information:
* [https://www.ettus.com/all-products/octoclock-g/ Product Page on Ettus]
* [https://kb.ettus.com/OctoClock_CDA-2990 OctoClock-G Knowledge Base]

== Installing and Configuring the UHD Software ==

This section explains how to build and install the USRP Hardware Driver (UHD) from source code.
At the time of this writing, we recommend using UHD version 4.8.

* 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.

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

<syntaxhighlight lang="bash">
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
</syntaxhighlight>

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

<syntaxhighlight lang="bash">
git clone https://github.com/EttusResearch/uhd.git
cd uhd
git checkout v4.8.0.0
</syntaxhighlight>

Build and install UHD:

<syntaxhighlight lang="bash">
mkdir build
cd build
cmake ../
make -j$(nproc)
sudo make install
sudo ldconfig
</syntaxhighlight>

Verify the installation:

<syntaxhighlight lang="bash">
uhd_usrp_probe
uhd_find_devices
</syntaxhighlight>

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

[[File:uhd_usrp_probe_output.png|400px|thumb|center|Example output of `uhd_usrp_probe` for USRP B210]]
[[File:uhd_find_devices_output.png|400px|thumb|center|Example output of `uhd_find_devices` for N310 and X410]]

----

== Installing and Configuring the USRP Radio ==

The USRP N300, N310, N320, N321, and X410 can all be used as either the gNB or 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/N320/N321 Getting Started Guide].
* These devices support all the channel bandwidths in FR1.

=== USRP N320 and N321 ===
* Setup is also covered in the [https://kb.ettus.com/USRP_N300/N310/N320/N321_Getting_Started_Guide USRP N300/N310/N320/N321 Getting Started Guide].
* These devices support all the channel bandwidths in FR1, and all except 400 MHz in FR2.

=== USRP X410 ===
* Refer to the [https://kb.ettus.com/USRP_X410/X440_Getting_Started_Guide USRP X410 Getting Started Guide] for detailed setup instructions.
* 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. These include:
* Setting the CPU governors
* Enabling thread priority scheduling
* Configuring socket buffer sizes
* Adjusting Ethernet MTU values
* Configuring network card ring buffer sizes

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

----

== Installing, Configuring, and Running the CN System ==
[[File:OAI_Core_Network.jpg|950px|center|thumb|OAI Core Network Deployment Architecture]]

The figure above illustrates the deployment architecture of the OpenAirInterface (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 <code>192.168.70.128/26</code>. The following components are shown:

* '''OAI-NRF (Network Repository Function)''' at <code>192.168.70.130</code> handles service registration and discovery.
* '''OAI-AMF (Access and Mobility Function)''' at <code>192.168.70.132</code> manages UE registration, connection, and mobility.
* '''OAI-SMF (Session Management Function)''' at <code>192.168.70.133</code> manages sessions and IP address allocation.
* '''OAI-UPF (User Plane Function)''' at <code>192.168.70.134</code> routes user data traffic and connects to the external data network via N3 interface.
* '''OAI-EXT-DN (External Data Network)''' at <code>192.168.70.135</code> provides Internet or service access for UEs.
* '''OAI-AUSF (Authentication Server Function)''' at <code>192.168.70.138</code> handles UE authentication.
* '''OAI-UDM (Unified Data Management)''' at <code>192.168.70.137</code> and '''OAI-UDR (Unified Data Repository)''' at <code>192.168.70.136</code> manage subscription and policy data.
* A '''MySQL Server''' is connected to <code>192.168.70.132</code> 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 CN5G 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 collocated with 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.

; Installation Commands
<syntaxhighlight lang="bash" enclose="none">
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>

<syntaxhighlight lang="bash" enclose="none">
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>

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

<syntaxhighlight lang="bash" enclose="none">
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 22.04 LTS
* CPU: 8 cores, x86_64 @ 3.5 GHz
* RAM: 32 GB

; Additional Requirement
* A second physical machine with the hardware requirements
* Proper IP routing between CN and gNB machines

; Installation Instructions
The same installation steps listed above should be executed on the second machine allocated for CN. Ensure that Docker and all dependencies are installed, and the <code>docker compose up -d</code> command is executed on the CN machine.

=== Core Network Database Configuration ===
To configure the OAI CN5G with a valid UE profile, manually insert subscriber information into the MySQL database by editing <code>oai_db.sql</code>.

; Navigate to DB scripts
<syntaxhighlight lang="bash" enclose="none">
cd ~/oai-cn5g/database
</syntaxhighlight>

; Insert subscriber entry (AuthenticationSubscription)
<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>

; Important Notes
* '''IMSI (International Mobile Subscriber Identity):''' The <code>ueid</code> and <code>supi</code> must match the IMSI used by your UE. Example IMSI: <code>208950000000032</code>.
* '''KEY:''' Permanent key shared between the UE and the core network. Example: <code>fec86ba6eb707ed08905757b1bb44b8f</code>
* '''OPC:''' Operator Code for milenage: <code>C42449363BBAD02B66D16BC975D77CC1</code>
* '''Authentication Method:''' Use <code>5G_AKA</code> for standard 5G UE authentication.

=== Update PLMN Configuration in <code>config.yaml</code> ===
To ensure proper PLMN configuration for the UE registration, update the <code>config.yaml</code> file to reflect the correct MCC, MNC, and SST.

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

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

* <code>mcc</code>: Set to <code>208</code> (France)
* <code>mnc</code>: Set to <code>95</code>
* <code>sst</code>: Set to <code>1</code> (default data slice)

Restart the CN stack:
<syntaxhighlight lang="bash" enclose="none">
cd ~/oai-cn5g
docker compose down
docker compose up -d
</syntaxhighlight>

=== Install Wireshark on Ubuntu ===
Wireshark is a widely used packet analyzer for monitoring network traffic.

* Update packages
<syntaxhighlight lang="bash" enclose="none">
sudo apt update
sudo apt upgrade -y
</syntaxhighlight>

* Install Wireshark
<syntaxhighlight lang="bash" enclose="none">
sudo apt install -y wireshark
</syntaxhighlight>

* Allow non-root capture (choose '''Yes''' when prompted)
If not prompted:
<syntaxhighlight lang="bash" enclose="none">
sudo dpkg-reconfigure wireshark-common
sudo usermod -aG wireshark $(whoami)
</syntaxhighlight>

* Launch Wireshark
<syntaxhighlight lang="bash" enclose="none">
sudo wireshark
</syntaxhighlight>

After launch, select the desired interface (e.g., <code>eth0</code>, <code>enp1s0</code>, <code>lo</code>, <i>oai-cn</i>) to start capturing packets.

=== Successful Launch of OAI CN5G Containers ===
Run:
<syntaxhighlight lang="bash" enclose="none">
sudo docker-compose up -d
</syntaxhighlight>

You should see output similar to the following, confirming container startup:
[[File:Start_up_OAI_CN.png|750px|center|thumb|Successful startup of OAI CN5G containers using Docker Compose]]

Each core network function such as <code>oai-amf</code>, <code>oai-smf</code>, <code>oai-upf</code>, <code>oai-nrf</code>, and supporting services like <code>mysql</code>, <code>oai-udm</code>, <code>oai-ausf</code>, etc., is instantiated as a Docker container. The message "<code>... done</code>" indicates successful creation and start.

=== Verification of Running CN5G Containers ===
Check container health:
<syntaxhighlight lang="bash" enclose="none">
sudo docker ps -a
</syntaxhighlight>

Expected view:
[[File:OAI_CN_Docker_Containers.png|750px|center|thumb|Docker containers for OAI CN5G core components running successfully]]

This confirms healthy status for <code>oai-amf</code>, <code>oai-smf</code>, <code>oai-upf</code>, <code>oai-nrf</code>, <code>oai-ausf</code>, <code>oai-udm</code>, <code>oai-udr</code>, <code>mysql</code>, <code>ims</code>, and <code>oai-ext-dn</code>.

=== Wireshark Monitoring of OAI CN5G ===
; Selecting the Interface
Choose the internal Docker network (e.g., <code>oai-cn5g</code>) to monitor inter-container traffic.
[[File:Wireshark_OAI.png|850px|center|thumb|Selecting the <code>oai-cn5g</code> interface in Wireshark to monitor 5G core container traffic]]

; Capturing Inter-Container Traffic
Live capture shows HTTP/2, TCP, and PFCP traffic among AMF, SMF, NRF, AUSF, etc.
[[File:Wireshark_Capture.png|1000px|center|thumb|Live capture view showing HTTP/2, TCP, and PFCP traffic between CN5G Docker containers]]

== Build Instructions for <code>srsRAN</code> ==

Follow the steps below to clone and build the <code>srsRAN_Project</code> from source.

=== Clone the Repository ===
<syntaxhighlight lang="bash" enclose="none">
git clone https://github.com/srsRAN/srsRAN_Project.git
</syntaxhighlight>

=== Build the Codebase ===
<syntaxhighlight lang="bash" enclose="none">
cd srsRAN_Project
mkdir build
cd build
cmake ../
make -j $(nproc)
sudo make test
sudo make install
</syntaxhighlight>

=== Run the gNB ===
After a successful build, you can run the gNB from:
<syntaxhighlight lang="bash" enclose="none">
/srsRAN_Project/build/apps/gnb/
</syntaxhighlight>

== Network Configuration for Separate CN Deployment ==

When the Core Network (CN) is deployed on a separate machine from the gNB, the following network configurations are required to ensure connectivity between the gNB and CN:

=== 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" enclose="none">
sudo ip route add 192.168.70.128/26 via 10.89.14.119 dev eno1
</syntaxhighlight>

* <code>192.168.70.128/26</code> is the subnet used by the CN Docker bridge network.
* <code>10.89.14.119</code> is the IP address of the CN host machine.
* <code>eno1</code> is the interface on the gNB machine connected to the CN machine. Replace with your actual interface name (e.g., <code>enp1s0</code>).

'''Note:''' This route is not persistent and will be lost after a reboot.

=== 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, configure:

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

* <code>net.ipv4.conf.all.forwarding=1</code> enables IPv4 forwarding in the Linux kernel.
* <code>iptables -P FORWARD ACCEPT</code> allows forwarded packets through the default filter chain.

These settings are temporary and will reset after reboot unless added to permanent configs such as:
* <code>/etc/sysctl.conf</code> (for forwarding)
* <code>iptables-persistent</code> or a systemd service (for iptables rules)

'''Note:''' This configuration is not needed if the CN is deployed on the same machine as the gNB.

== Invoking the gNB ==

After configuring the gNB, invoke it using the following procedure.

=== Copy the Configuration File ===
First, copy the edited gNB configuration file to the build directory:
<syntaxhighlight lang="bash" enclose="none">
cp /srsRAN_Project/configs/gnb_rf_b200_fdd_srsUE.yml /srsRAN_Project/build/apps/gnb/
</syntaxhighlight>

=== gNB Configuration File for srsRAN ===
Below is an excerpt of the customized <code>gnb.yaml</code> used to configure the srsRAN gNB for interoperability with the OAI Core Network. Key parameters: AMF address, bind address, PLMN, TAC, and network slice information.

; Modified Fields
* <code>amf.addr:</code> <code>192.168.70.132</code> – IP address of the OAI AMF.
* <code>bind_addr:</code> <code>10.88.136.29</code> – IP address of the host running the gNB software.
* <code>tac:</code> <code>1</code> – Tracking Area Code; must match the OAI CN.
* <code>plmn:</code> <code>20895</code> – PLMN (MCC = 208, MNC = 95), consistent across CN and RAN.
* <code>sst:</code> <code>1</code> – Slice/Service Type for the configured PLMN.

; YAML Snippet
<syntaxhighlight lang="yaml">
cu_cp:
amf:
addr: 192.168.70.132
port: 38412
bind_addr: 10.88.136.29
supported_tracking_areas:
- tac: 1
plmn_list:
- plmn: "20895"
tai_slice_support_list:
- sst: 1
</syntaxhighlight>

Make sure these parameters are consistent with your <code>config.yaml</code> in the OAI Core Network (PLMN, TAC, SST) to ensure successful NGAP registration and PDU session establishment.

=== Launch the gNB ===
After configuring <code>gnb_rf_b210_fdd_srsUE.yml</code>, launch the gNB:
<syntaxhighlight lang="bash" enclose="none">
cd ~/srsRAN_Project/build/apps/gnb
sudo ./gnb -c gnb_rf_b210_fdd_srsUE.yml
</syntaxhighlight>

This initializes the gNB using the specified YAML configuration file. Ensure the file includes correct values for <code>amf.addr</code>, <code>bind_addr</code>, <code>plmn</code>, <code>tac</code>, and RF parameters suitable for your USRP B210 and deployment scenario.

== Verifying with Wireshark ==

[[File:Wireshark_OAI_NGAP.png|750px|center|thumb|Wireshark capture showing successful NGSetupRequest and NGSetupResponse between gNB and AMF.]]

Wireshark can verify NGAP signaling between the gNB and the Core Network (CN). The interface to monitor depends on your deployment setup:

* '''Scenario A: CN and gNB on Separate Machines'''
** On the '''CN machine''', start Wireshark and select the <code>oai-cn5g</code> network interface.
** On the '''gNB machine''', start Wireshark and select the Ethernet interface (e.g., <code>eno1</code>) connected to the CN machine.
** Start capturing on both to monitor NGAP and related 5G signaling traffic.

* '''Scenario B: CN and gNB on Same Machine'''
** Start Wireshark and select only the <code>oai-cn5g</code> interface.
** All internal signaling between gNB and CN containers will be visible on this interface.

'''Expected Behavior:'''
* After the gNB launches, it should initiate an <code>NGAP Setup Request</code> to the AMF.
* The AMF should respond with an <code>NGAP Setup Response</code> if MCC, MNC, and TAC match.

'''Troubleshooting Tips:'''
* Ensure MCC, MNC, and SST are consistent in the gNB config and CN YAML.
* Verify the TAC (Tracking Area Code) matches on both sides.
* Check that the static route (if used) is set correctly and that Ethernet connectivity between gNB and CN is functional.

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

'''srsUE''' is a software-defined UE implementation using SDR (e.g., USRP B210).
''Limitations'': The current 5G SA srsUE application has several constraints that impact gNB and core configuration:
* Limited to '''15 kHz SCS''' → FDD bands only
* Supported bandwidths: '''5, 10, 15, 20 MHz'''

=== Building and Installing srs UE (4G) ===
To set up the srsRAN 4G UE software stack, follow the steps below.

* Clone the repository:
<syntaxhighlight lang="bash" enclose="none">
git clone https://github.com/srsRAN/srsRAN_4G.git
cd srsRAN_4G
</syntaxhighlight>

* Create a build directory and compile:
<syntaxhighlight lang="bash" enclose="none">
mkdir build
cd build
cmake ../
make
make test
</syntaxhighlight>

* Install binaries and default configs:
<syntaxhighlight lang="bash" enclose="none">
sudo make install
srsran_install_configs.sh user
</syntaxhighlight>

This installs the necessary binaries and default configuration files for srsUE. You can now configure UE parameters and launch the UE application.

=== Configuring srs UE for OAI Core Network ===
Key settings for interoperability:
* '''USIM Parameters''': <code>IMSI</code>, <code>K</code>, and <code>OPC</code> '''must match''' the entries in the Core Network DB.
* '''APN''': Typically <code>oai</code> to match core configuration.
* '''Device''': <code>device_args = type=b200</code> for USRP B210.

<syntaxhighlight lang="ini">
[rf]
freq_offset = 0
tx_gain = 50
rx_gain = 80
srate = 23.04e6
nof_antennas = 1

device_name = uhd
device_args = type=b200
clock = internal
time_adv_nsamples = 300

[usim]
mode = soft
algo = milenage
opc = C42449363BBAD02B66D16BC975D77CC1
k = fec86ba6eb707ed08905757b1bb44b8f
imsi = 208950000000032
imei = 353490069873319

[nas]
apn = oai
apn_protocol = ipv4

[rrc]
release = 15
ue_category = 4

[pcap]
enable = none
mac_filename = /tmp/ue_mac.pcap
mac_nr_filename = /tmp/ue_mac_nr.pcap
nas_filename = /tmp/ue_nas.pcap

[log]
all_level = info
filename = /tmp/ue.log

[rat.nr]
bands = 3
nof_carriers = 1
nof_prb = 106
max_nof_prb = 106
</syntaxhighlight>

=== Invoking the srs UE with USRP B210 ===
Run from the build directory:
<syntaxhighlight lang="bash" enclose="none">
~/srsRAN_4G/build/srsue/src$ sudo ./srsue ue_rf.conf
</syntaxhighlight>

=== Verifying srs UE IP Assignment ===
After PDU session establishment, verify the tunnel interface (e.g., <code>tun_srsue</code>):

<syntaxhighlight lang="bash" enclose="none">
ifconfig tun_srsue
</syntaxhighlight>

Example output:
<syntaxhighlight lang="text">
tun_srsue: flags=4305<UP,POINTOPOINT,RUNNING,NOARP,MULTICAST> mtu 1500
inet 10.0.0.12 netmask 255.255.255.0 destination 10.0.0.12
RX packets 0 bytes 0 (0.0 B)
TX packets 40 bytes 6920 (6.9 KB)
</syntaxhighlight>

In this example, the UE received IP <code>10.0.0.12</code> from the OAI 5G Core.

=== srsRAN Log Interpretation for srsUE Attachment and PDU Session Setup ===
Annotated logs showing RA, RRC, NGAP, and PDU session setup:

<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_RRC] RRCSetupComplete received — UE is now RRC_CONNECTED ✅
[NGAP] UE 1: Chose AMF 'OAI-AMF' (PLMN MCC 208, MNC 95)
...
[PDU SESSION SETUP INITIATED]
[GTPU] Tunnel Created: TEID: bf57e042 ↔ 192.168.70.134
...
[NR_RRC] RRCReconfigurationComplete received ✅
</syntaxhighlight>

; Legend
* '''RA procedure succeeded''' – Msg4 ACK received
* '''RRC_CONNECTED''' – UE has RRC connection
* '''SecurityModeComplete''' – Security context active
* '''PDU Session Setup''' – Bearer/tunnel configured

=== srsUE Log Interpretation for Initial Access and Registration ===
Launch UE:
<syntaxhighlight lang="bash" enclose="none">
cd ~/srsRAN_4G/build/srsue/src
sudo ./srsue ue_rf.conf
</syntaxhighlight>

Typical successful trace:
<syntaxhighlight lang="text">
[INFO] [UHD] ... UHD_4.8.0 ...
[INFO] [B200] Detected Device: B210 (USB 3)
...
Random Access Complete. c-rnti=0x4601, ta=4
RRC Connected
PDU Session Establishment successful. IP: 10.0.0.8
RF status: O=2, U=0, L=0
</syntaxhighlight>

== Verifying srsUE Attach and Registration via Wireshark ==
A Wireshark capture of NGAP and NAS signaling confirms:
* NG Setup (NGSetupRequest/Response)
* NAS Registration (InitialUEMessage → Registration Request)
* Authentication and Security Mode procedures
* UE Capability exchange
* Initial Context Setup
* PDU Session Resource Setup

[[File:Wireshark_Packet_Capture.png|900px|center|thumb|NGAP and NAS signaling during UE attach and registration.]]

== End-to-End Connectivity Verification via Ping ==
From the external DN container:
<syntaxhighlight lang="bash" enclose="none">
sudo docker exec -it oai-ext-dn ping 10.0.0.5
</syntaxhighlight>

Expected:
<syntaxhighlight lang="text">
64 bytes from 10.0.0.5: icmp_seq=1 ttl=63 time=35.0 ms
...
7 packets transmitted, 7 received, 0% packet loss
</syntaxhighlight>

Confirms UE registration, PDU session, and correct UPF forwarding.

== iPerf Downlink (DL) Testing ==
; Server on UE (bind to UE tunnel IP)
<syntaxhighlight lang="bash" enclose="none">
sudo iperf -s -i 1 -u -B 10.0.0.5
</syntaxhighlight>

; Client on CN/gNB
<syntaxhighlight lang="bash" enclose="none">
sudo docker exec -it oai-ext-dn iperf -c 10.0.0.5 -u -b 10M --bind 192.168.70.135
</syntaxhighlight>

Example results show ~10.5 Mbit/s, 0% loss, sub-1 ms jitter.

== iPerf Uplink (UL) Testing ==
; Server on CN
<syntaxhighlight lang="bash" enclose="none">
sudo docker exec -it oai-ext-dn iperf -s -i 1 -u -B 192.168.70.135
</syntaxhighlight>

; Client on UE
<syntaxhighlight lang="bash" enclose="none">
iperf -c 192.168.70.135 -u -b 10M --bind 10.0.0.5
</syntaxhighlight>

Expected: stable UL throughput, low jitter, no loss.

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

=== Quectel RM520N Series — 5G NR Sub-6 GHz Module ===
; Key Features
* 5G SA/NSA (3GPP Rel-16), M.2 30×52×2.3mm
* Migration compatible with RM50xQ/EM06/EM12/EM160R-GL

; Performance
* SA: DL up to 2.4 Gbps / UL up to 900 Mbps
* NSA: DL up to 3.4 Gbps / UL ~550–600 Mbps

; Environment
* –40°C…+85°C (extended), global carrier support

; GNSS
* Qualcomm IZat Gen9C Lite: GPS/GLONASS/BDS/Galileo/QZSS

=== Configuring the SIM Card ===
If using a modem or COTS handset, a SIM is required (OAI UE softmodem on USRP does not require one).

Open-Cells SIM (ADM code printed on SIM). Read current data:
<syntaxhighlight lang="bash" enclose="none">
sudo ./program_uicc --adm 1
</syntaxhighlight>

Example (failure due to wrong ADM length):
<syntaxhighlight lang="text">
No ADM code of 8 figures, cannot program the UICC
</syntaxhighlight>

Use the correct 8-digit ADM (example):
<syntaxhighlight lang="bash" enclose="none">
sudo ./program_uicc --adm 0C008080
</syntaxhighlight>

Successful programming and authentication example:
<syntaxhighlight lang="bash" enclose="none">
sudo ./program_uicc --adm QC008080 \
--key 8C6A145D419B107F93501CC02255D4C6 \
--opc 1DB7A0E55282194FC145F9B9F184979D \
--authenticate
</syntaxhighlight>

[[File:800px-quectel-ue-program_uicc_output_for_read.jpg|600px|center|thumb|UICC programming failure due to incorrect ADM length.]]
[[File:800px-quectel-ue-program_uicc_output_for_write.jpg|900px|center|thumb|Successful UICC programming and 5G AKA authentication.]]

Ensure SIM values match the CN SQL database. Primary parameters:

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

=== Serial Connection to the Module via Minicom ===
Attach antennas, insert the module (M.2), connect via USB 3.0.

Install and start Minicom:
<syntaxhighlight lang="bash" enclose="none">
sudo apt-get install minicom
sudo minicom /dev/ttyUSB0
</syntaxhighlight>
Exit: <code>Ctrl-A</code>, then <code>X</code>.

=== Quectel Module Configuration via AT Commands ===
Execute in Minicom (order):

# <code>AT+GMR</code> – Firmware version
# <code>AT+CIMI</code> – IMSI
# <code>AT+GSN</code> – IMEI
# <code>AT+QMBNCFG="select","ROW_Commercial"</code> – Enable commercial profile
# <code>AT+QNWPREFCFG="nr5g_band"</code> – Show NR bands
# <code>AT+QNWPREFCFG="mode_pref"</code> – Show mode
# <code>AT+QNWPREFCFG="mode_pref",nr5g</code> – Prefer NR SA
# <code>AT+QNWPREFCFG="nr5g_disable_mode",0</code> – Enable NR
# <code>AT+CGDCONT=1,"IP","oai","0.0.0.0",0,0</code> – PDP context
# <code>AT+CFUN=0</code> then <code>AT+CFUN=1</code> – Cycle functionality

==== Verifying Operation with AT Commands ====
; <code>AT+COPS?</code> – Operator & registration
Expected:
<syntaxhighlight lang="text">
+COPS: 0,0,"208 92 open cells",11
</syntaxhighlight>

; <code>AT+C5GREG?</code> – 5G registration
Expected:
<syntaxhighlight lang="text">
+C5GREG: 2,1,"1","0",11,16,"01.00007B;00.000000:01.00000C;00.000000"
</syntaxhighlight>

Connectivity testing of COTS UE with OAI gNB/CN via ping and iperf follows the same steps as above.

; Example OOKLA Speedtest (COTS UE)
* Downlink: '''48.93 Mbps'''
* Uplink: '''4 Mbps'''
* Latency: ~'''50 ms'''

5G srsRAN End-to-End Reference Architecture with USRP

2025-11-05T17:48:55Z

NeelPandeya: Created page with "== Application Note Number and Authors == '''AN-599''' == Authors == Bharat Agarwal and Neel Pandeya ==Executive Summary== ===Overview=== This Application Note presents..."

== Application Note Number and Authors ==

'''AN-599'''

== Authors ==

Bharat Agarwal and Neel Pandeya

==Executive Summary==

===Overview===

This Application Note presents ...

[[Category:Application Notes]]

AI-Based Spectrum Sensing with Nvidia Jetson and USRP

2025-11-05T12:35:14Z

NeelPandeya: /* Waveform Repository */

== Application Note Number and Authors ==

'''AN-811'''

== Authors ==

Bharat Agarwal and Neel Pandeya

== Executive Summary ==

This application note presents a complete framework for real-time spectrum sensing using NI Universal Serial Radio Peripheral (USRP) Software-Defined Radios (SDRs) and NVIDIA Jetson or standard x86 compute platforms. The framework is not limited to a single USRP model—the X410, X310, and B2xx series (e.g., B206) can all be used as transmitters or receivers depending on the deployment scenario. The solution leverages the NI-RF Data Recording API to enable scalable RF data acquisition, SigMF-compliant metadata tagging, and seamless integration with machine learning workflows.

The document outlines three core usage scenarios:

# x86-Based Development Workflow: Using a workstation or server-class x86 machine, paired with high-end USRPs such as the X410 or X310, the system supports wideband spectrum sensing (up to 400 MHz instantaneous bandwidth per channel). This configuration is ideal for laboratory development, algorithm training, and high-throughput dataset generation.
# Jetson-Based Embedded Sensing (Primary Use Case): Using an NVIDIA Jetson platform as the host (e.g., AGX Orin) with a compact B206 SDR as receiver and an X410 as transmitter, the system delivers efficient edge inference with GPU acceleration. Although the B206 limits the instantaneous bandwidth to 56 MHz, this configuration emphasizes portability, low power, and real-time embedded operation.
# User-Defined Dataset Integration: In addition to live spectrum sensing, the framework supports integration and generation of user-defined datasets. This functionality extends the applicability of the system beyond real-time capture, enabling flexible experimentation, reproducibility, and seamless AI/ML dataset preparation. Two complementary capabilities are supported:
## SigMF Dataset Recording
##* All captured RF data is stored in the Signal Metadata Format (SigMF).
##* SigMF pairs raw IQ samples (<code>.sigmf-data</code>) with a corresponding metadata file (<code>.sigmf-meta</code>) in JSON format.
##* Metadata describes acquisition parameters such as frequency, bandwidth, gain, device type, timestamps, and scenario context.
##* Being human-readable and portable, SigMF datasets can be used across a wide range of software environments, making them ideal for wireless research, spectrum monitoring, AI/ML training for 6G, and regulatory validation.
##* Example: A spectrum sensing session at 3.5 GHz, 20 MHz bandwidth, and 10-second duration will result in a SigMF-compliant dataset ready for further processing or ML-based classification.
## Continuous Waveform Playback with User-Defined Files
##* The platform supports continuous transmission and replay of user-defined waveforms in TDMS or MATLAB (.mat) formats.
##* This allows testing with standard-compliant signals such as 5G NR, LTE, Radar, or Wi-Fi, or custom-designed waveforms.
##* By replaying predefined waveforms, researchers can benchmark algorithms, validate coexistence scenarios, and reproduce experiments consistently across testbeds.
##* Example: A MATLAB-generated LTE downlink frame can be continuously transmitted via an X410 while a B206 or X310 records the received signal in SigMF format for classification.

Together, these capabilities ensure that the NI-RF Data Recording API can handle both dataset creation (SigMF-based recording) and waveform-driven experimentation (TDMS/MAT playback), thereby covering the entire pipeline from signal generation to ML-ready dataset production.

By combining NI's reliable SDR hardware with NVIDIA's efficient edge compute platforms and a unified data interface, this solution supports a wide range of spectrum intelligence applications—from interference detection and dynamic spectrum access to embedded RF analytics. The methodology enables scalable deployment from lab to field, supporting real-time insights and long-term data collection in a streamlined, modular pipeline.

== USRP B206 Overview ==

[[File: USRP-b206_mini_01.jpg|thumb|center|400px|NI USRP B206 Software Defined Radio]]

The USRP B206 is a compact, low-cost SDR developed by NI / Ettus Research. It supports full-duplex operation with one transmit and one receive channel, making it ideal for a variety of wireless communication and sensing applications. The B206 covers a wide RF frequency range from 70 MHz to 6 GHz and supports up to 56 MHz of instantaneous bandwidth. This makes it suitable for applications such as spectrum sensing, dynamic spectrum access, and cognitive radio.

The device connects to a host system via a high-speed USB 3.0 interface, which enables data rates sufficient for wideband real-time signal acquisition and transmission. It also supports USB 2.0 with reduced performance. The B206 includes a Xilinx Spartan-6 FPGA for onboard signal processing and is powered either through USB or an external DC supply, the latter being preferred for optimal RF performance.

The USRP B206 is compatible with both x86 and ARM-based hosts, including embedded platforms like the NVIDIA Jetson series. This enables portable and energy-efficient deployment of spectrum sensing pipelines at the network edge. It is fully supported by the open-source UHD and integrates with popular SDR development tools such as GNU Radio, MATLAB, and LabVIEW.

Typical use cases for the B206 include real-time spectrum monitoring, wireless signal classification using machine learning, prototyping of 4G/5G systems, and SDR education and training. Its compact size and flexible software support make it an excellent choice for both laboratory research and embedded field deployments.

'''Key Features of the USRP B206:'''
* RF Capabilities: 1 TX, 1 RX, independently tunable, RF transceiver, 70 MHz to 6 GHz, up to 56 MHz bandwidth
* Programmable Logic: FPGA: Xilinx Spartan-6 XC6SLX150
* Software: UHD 4.9 or later, GNU Radio, C/C++ and Python
* Synchronization: REF (external 10 MHz or PPS reference)
* Digital Interfaces: USB 3.0, GPIO (8 I/O lines with 3.3 V I/O voltage), and JTAG
* Power, form factor: 5 V DC, 0.9 A maximum; Board-only: 84.3 mm × 51.0 mm × 8.7 mm; Enclosed: 84.9 mm × 55.7 mm × 19.8 mm

== NI-RF Data Recording API Overview ==

The '''[https://github.com/ni/ni-rf-data-recording-api/blob/main/README.md NI-RF Data Recording API]''' is an open-source, Python-based framework developed by National Instruments (NI) in collaboration with the Genesys Lab at Northeastern University. It is designed to streamline RF data collection using NI USRP SDRs, with support for structured metadata via the '''[https://github.com/sigmf/SigMF Signal Metadata Format (SigMF)]'''.

=== Purpose and Scope ===
This API enables efficient recording, labeling, and replay of real-world RF signals. It is particularly suited for generating datasets used in AI/ML workflows, wireless research, and spectrum monitoring. The framework abstracts low-level UHD interactions, allowing users to define RF parameters through JSON or YAML configuration files.

=== Key Features ===
* Support for both signal transmission and reception using NI USRP hardware.
* Native recording in SigMF format, capturing both IQ samples and rich metadata.
* Python-based, modular architecture supporting custom extensions and automation.
* Multi-SDR support via coordinated configuration files.
* Sample waveform libraries included (e.g., LTE, NR, radar, Wi-Fi) in TDMS/MAT formats.
* Utility scripts for standalone use: transmit, receive, replay, or continuous capture.

=== System Requirements ===
The API has been validated on Ubuntu 22.04 systems with the following dependencies:
* At least one compatible NI USRP device (e.g., B206, X310, X410).
* Installed UHD drivers with Python bindings.
* Python 3.x and required libraries (e.g., NumPy, PyYAML).
* Optional Docker environment for containerized deployment.

=== Relevance to Our Use Cases ===
In this application note, we explore three deployment scenarios of the NI-RF Data Recording API:

# x86-based Spectrum Sensing: Using the API on a desktop or server-class system, the USRP B206 is configured to perform spectrum capture, and the data is saved in SigMF format. This setup is optimal for high-throughput and lab-based development environments.
# Embedded Jetson Platform: The API is deployed on an NVIDIA Jetson device interfaced with the USRP B206 over USB 3.0. This enables compact, power-efficient, and real-time spectrum sensing at the edge. Onboard GPU resources are leveraged for FFT computation and ML inference.
# User-Defined Dataset Integration: The API provides flexible support for user-defined datasets through two complementary capabilities:
## Importing Pre-Generated Data: Users can seamlessly import and tag custom IQ recordings (e.g., SigMF-compliant files or previously captured spectrum data) into the repository. This enables integration of external datasets for benchmarking, anomaly detection, or reproducible research.
## Data Lake Storage for AI/ML Pipelines: All captured and imported datasets can be stored in a structured data lake, significantly simplifying automated dataset selection, management, and preprocessing. This facilitates streamlined workflows for AI/ML model design, training, and validation in spectrum sensing and 6G wireless research.

The NI-RF Data Recording API provides a flexible, hardware-agnostic foundation for both live RF capture and offline dataset handling, making it central to spectrum intelligence and edge-aware signal processing workflows.

== Reference Architecture for Spectrum Sensing ==

To support flexible and scalable RF data collection workflows, we propose a dual-mode reference architecture that demonstrates spectrum sensing using NI USRP hardware with two compute platforms: a high-performance x86 host and an embedded NVIDIA Jetson device. Both configurations utilize the NI-RF Data Recording API to capture, store, and manage RF data in SigMF format. The hardware setup supports real-time signal acquisition, tagging, and streaming for downstream machine learning or signal intelligence tasks.

=== x86-Based High-Performance Architecture ===

[[File: x86.png|thumb|center|900px|x86-based spectrum sensing architecture using NI USRP B206 and X410]]

In this high-performance lab-based deployment, a desktop-class x86 host system is used. The USRP X410 (or alternatively the X310) serves as the receiver, connected to the workstation via a 10 GbE Ethernet interface to support high-throughput data streaming. The transmitter is also an NI USRP X410, connected through a 10 GbE link via a network switch. A 30 dB attenuator is inserted between the TX and RX paths to protect the RF front-end from saturation during close-proximity transmission.

This configuration demonstrates the full high-performance capability of the platform, enabling wideband spectrum sensing and scalable data capture.

Host System Specifications:
* Operating System: Ubuntu 22.04
* UHD Compatibility: The NI-RF Data Recording API supports UHD ≥ 4.2. Most devices such as the X410 or X310 work with older versions, but the B206 requires UHD ≥ 4.9.
* Processor: Intel Xeon w7-2495X (24 cores, 2.5 GHz)

This setup is suited for '''high-throughput spectrum recording, algorithm development, and dataset generation''' in a lab environment. It offers large storage capacity, stable power, and CPU-intensive post-processing capabilities.

=== Jetson-Based Embedded Architecture ===

[[File:SS_with_x86.png|thumb|center|900px|Jetson-based spectrum sensing architecture using NI USRP B2x0 and X410]]

In this configuration, an NVIDIA Jetson module serves as the edge processing unit. The Jetson connects to a USRP B2x0 (e.g., B206) over a USB 3.0 interface, acting as the spectrum sensor (receiver). A USRP X410 acts as the transmitter, linked via a LAN switch. A 30 dB attenuator is used between the TX and RX paths to prevent RF front-end saturation during close-proximity transmission.

The Jetson executes the RF data acquisition pipeline and leverages onboard GPU resources to perform high-speed FFTs, signal classification, and real-time metadata tagging. A display, keyboard, and mouse connect directly for standalone operation.

'Jetson System Specifications:
* Operating System: Ubuntu 22.04 with JetPack 6.2.1
* UHD Version: 4.9
* Processor: NVIDIA Jetson AGX Orin 64 GB

This configuration is ideal for low-power, field-deployable sensing nodes where edge inference, minimal latency, and portability are required. The NI-RF Data Recording API runs natively on ARM-based Jetson, ensuring consistent data acquisition across architectures.

=== Common Features Across Architectures ===
Both architectures support:
* Real-time IQ sample recording and metadata tagging using NI-RF Data Recording API
* Integration with SigMF-compliant datasets
* Wideband RF capture across 70 MHz–6 GHz (with B206)
* Configurable gain, center frequency, bandwidth, and LO offsets via JSON/YAML files

The dual-platform design allows researchers to prototype, validate, and deploy spectrum sensing pipelines in a variety of scenarios—from power-constrained edge sensing to scalable, cloud-connected research environments.

== Bill of Materials ==

This section lists the hardware and software components required to replicate the spectrum sensing setup described in the reference architectures.

=== Jetson-Based Embedded Spectrum Sensing Setup ===
* '''NI USRP B206 SDR (Receiver)'''
** Frequency Range: 70 MHz – 6 GHz
** Bandwidth: up to 56 MHz
** Interface: USB 3.0

* '''NI USRP X410 SDR (Transmitter)'''
** Frequency Range: up to 7.2 GHz
** Bandwidth: up to 1 GHz per channel
** Interface: 10 GbE (SFP+)

* '''NVIDIA Jetson AGX Orin 64 GB Developer Kit (Edge Host)'''
** GPU: 2048-core Ampere GPU
** Interfaces: USB 3.0, 10 Gb Ethernet
** OS: Ubuntu 22.04 (ARM64) with JetPack 6.2.1

* '''Display and Input Devices'''
** Monitor (DisplayPort or HDMI)
** USB Keyboard and Mouse

* '''30 dB RF Attenuator'''
** Protects RX frontend during loopback or close-range transmission

* '''Network Switch (Gigabit)'''
** Routes LAN traffic between Jetson and X410

* '''RF Cables and Antennas or Dummy Load'''
* '''Power Supply for USRP X410 and Jetson'''
* '''USB 3.0 Cable (for Jetson–B206 interface)'''

=== x86-Based Spectrum Sensing Setup ===
* '''NI USRP B206 SDR (Receiver)'''
* '''NI USRP X410 SDR (Transmitter)'''
* '''x86 Workstation or Server (Host PC)'''
** CPU: Intel Xeon w7-2495X, 24 cores, 2.5 GHz
** OS: Ubuntu 22.04 LTS
** UHD: Version 4.8 or newer
** RAM: Minimum 32 GB recommended
** Storage: SSD for high-speed IQ data logging

* '''Display and Input Devices'''
** Monitor (DisplayPort or HDMI)
** USB Keyboard and Mouse

* '''30 dB RF Attenuator'''
* '''USB 3.0 Cable (PC–B206 interface)'''
* '''Ethernet Cables (PC and X410 to switch)'''
* '''Network Switch (Gigabit or 10 GbE)'''
* '''Coaxial Cable (RF connection between TX and RX)'''

=== Software Requirements (Common) ===
* '''NI-RF Data Recording API'''
** GitHub: [https://github.com/ni/ni-rf-data-recording-api https://github.com/ni/ni-rf-data-recording-api]
** Supports SigMF format, YAML/JSON configuration, UHD interface

* '''UHD (USRP Hardware Driver)'''
** Version 4.9 recommended
** Installed natively

* '''Python 3.x Environment'''
** Required packages: numpy, pyyaml, sigmf, uhd, etc.

== Hardware Requirements ==

To implement the proposed spectrum sensing architecture, the following hardware components are required. The selected devices are chosen for their compatibility with the NI-RF Data Recording API, support for UHD drivers, and ability to perform high-speed RF acquisition and processing.

=== NI USRP B206 (Receiver SDR) ===
The USRP B206 is a low-cost, full-duplex software-defined radio with wide RF coverage and USB 3.0 connectivity, making it ideal for spectrum sensing tasks.

* '''Frequency Range:''' 70 MHz – 6 GHz
* '''Bandwidth:''' Up to 56 MHz
* '''Interface:''' USB 3.0
* '''Form Factor:''' Compact, bus-powered or DC-powered
* '''Purchase Link:''' [https://www.ettus.com/all-products/usrp-b200/ https://www.ettus.com/all-products/usrp-b200/]

=== NI USRP X410 (Transmitter SDR) ===
The USRP X410 is a high-performance, 4-channel SDR capable of wideband signal transmission and reception. It supports 10 GbE connectivity and real-time FPGA processing.

* '''Frequency Range:''' Up to 7.2 GHz
* '''Bandwidth:''' Up to 1 GHz per channel
* '''Interface:''' 10 GbE (SFP+), PCIe (optional)
* '''FPGA:''' Xilinx Zynq Ultrascale+ RFSoC
* '''Purchase Link:''' [https://www.ettus.com/all-products/usrp-x410/ https://www.ettus.com/all-products/usrp-x410/]

=== NVIDIA Jetson AGX Orin 64 GB Developer Kit (Edge Host) ===
The Jetson AGX Orin series provides a powerful embedded GPU platform for edge AI and RF signal processing.

* '''GPU:''' NVIDIA Ampere architecture
* '''RAM:''' 32 GB / 64 GB LPDDR4/5
* '''Connectivity:''' USB 3.0, Ethernet, GPIO
* '''OS Support:''' Ubuntu 20.04 / 22.04 (ARM64)
* '''Purchase Link:''' [https://store.nvidia.com/jetson/store/ https://store.nvidia.com/jetson/store/]

=== Network Switch (Gigabit or 10 GbE) ===
A managed or unmanaged Ethernet switch is required to route LAN traffic between the Jetson or x86 host and the USRP X410.

* '''Recommended:''' Netgear GS108, Mikrotik CRS305, or Cisco CBS350
* '''Typical Ports:''' 8+ (Gigabit or 10 GbE SFP+)
* '''Example Link:''' [https://www.netgear.com/business/wired/switches/smart/gs108/ https://www.netgear.com/business/wired/switches/smart/gs108/]

=== High-Performance x86 Host (Optional for Lab Use) ===
An x86 workstation is recommended for development, high-throughput data collection, or as an alternative to Jetson in a lab environment.

* '''Processor:''' Minimum specification of an 8-core CPU at 3 GHz or higher (e.g., Intel Xeon or equivalent). Higher core counts (e.g., 24-core Xeon W7-2495X) can improve throughput and parallel data processing but are not mandatory.
* '''RAM:''' 64 GB or more
* '''Storage:''' NVMe SSD for high-speed data logging
* '''Operating System:''' Ubuntu 22.04 LTS
* '''Form Factor:''' Tower workstation or server

=== RF Accessories ===
* '''RF Coaxial Cables (SMA)'''
* '''30 dB Attenuator''' – Protects RX during close TX–RX loopback tests
* '''Antennas''' (Wideband or band-specific)
* '''Dummy Load''' (for isolated lab TX tests)
* '''USB 3.0 Cable''' (for USRP B206)
* '''Ethernet Cables''' (Cat 6 or SFP+ DAC for X410)
* '''Power Supplies:'''
** Jetson: 19 V / 4.74 A adapter (usually included)
** X410: External DC or rack supply per specifications

== Software Requirements ==

This section outlines the required software components for enabling spectrum sensing using the NI-RF Data Recording API with USRP B206/X410 and NVIDIA Jetson or x86 hosts. These tools are compatible across both embedded and desktop-class platforms and support real-time signal acquisition and metadata tagging in SigMF format.

=== Ubuntu Operating System ===
* '''Version:''' Ubuntu 22.04 LTS (Jetson) / Ubuntu 22.04 LTS (x86 recommended)
* '''Download Link:''' [https://ubuntu.com/download https://ubuntu.com/download]
* '''Jetson OS Image:''' JetPack SDK includes Ubuntu and NVIDIA drivers
* '''JetPack Link:''' [https://developer.nvidia.com/embedded/jetpack https://developer.nvidia.com/embedded/jetpack]

=== NI-RF Data Recording API ===
* '''Description:''' Open-source Python API developed by NI and the Genesys Lab (Northeastern University) for recording and labeling RF data in SigMF format using USRP devices.
* '''Features:''' Configurable YAML/JSON setups, multi-SDR coordination, SigMF conversion, supports transmission/reception workflows.
* '''Repository:''' [https://github.com/ni/ni-rf-data-recording-api https://github.com/ni/ni-rf-data-recording-api]

=== UHD – USRP Hardware Driver ===
* '''Description:''' The official driver and API library for controlling and interfacing with all NI/Ettus USRP SDR hardware. Required for low-level communication between Python and the hardware.
* '''Version:''' The NI-RF Data Recording API requires a UHD version that supports the selected USRP device:
** For X410 (and other X-Series): UHD ≥ 4.2 (first stable release UHD 4.4 recommended)
** For B206: UHD ≥ 4.9 required
* '''Repository:''' [https://github.com/EttusResearch/uhd https://github.com/EttusResearch/uhd]
* '''Install Guide:''' [https://kb.ettus.com/Building_and_Installing_the_USRP_Open-Source_Toolchain_(UHD_and_GNU_Radio)_on_Linux UHD and GNU Radio Install Guide]

=== Python Environment ===
* '''Version:''' Python 3.10.12 or newer
* '''Required Packages:'''
** <code>numpy</code>, <code>pyyaml</code>, <code>sigmf</code>, <code>uhd</code>, <code>scipy</code>, <code>matplotlib</code>, etc.
* '''Package Manager:''' <code>pip</code> or <code>conda</code>
* '''Recommended Setup:''' Create a Python virtual environment for isolation and reproducibility.
* '''Download Link:''' [https://www.python.org/ https://www.python.org/]

=== SigMF Library (Python) ===
* '''Description:''' Used for generating and parsing metadata in the Signal Metadata Format (SigMF), enabling dataset interoperability and ML dataset labeling.
* '''Supported Version:''' Validated with '''SigMF 1.0.0''' (later versions such as 1.1.x or 1.2.x introduce major changes and have not been validated).
* '''Repository:''' [https://github.com/gnuradio/sigmf-numpy https://github.com/gnuradio/sigmf-numpy]
* '''Installation Command:''' <code>pip install sigmf==1.0.0</code>
* '''Reference:''' For more details, see the [https://github.com/ni/ni-rf-data-recording-api/tree/main/docs NI RF Data Recording API Getting Started Guide].

== Installing and Configuring the UHD Software ==

This section explains how to build and install the USRP Hardware Driver (UHD) from source code. At the time of this writing, the recommended version is '''UHD 4.9'''.

* It is strongly recommended to build UHD from source rather than installing from binary packages to ensure compatibility and access to the latest updates.
* For x86/64 Ubuntu systems with released UHD versions available, you may install via APT Debian packages.
* For Jetson (ARM64) systems, UHD must be built from source since no binary packages are provided.

---

Before building UHD, install all required dependencies (Ubuntu 22.04):

'''Note:''' If your system already has another UHD version installed, remove it first:

<syntaxhighlight lang="bash">
sudo apt remove libuhd* uhd-host
sudo rm -rf /usr/lib/uhd /usr/include/uhd /usr/local/lib/uhd /usr/local/include/uhd
</syntaxhighlight>

Then install build dependencies:

<syntaxhighlight lang="bash">
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
</syntaxhighlight>

Clone the UHD repository and check out version '''v4.9.0.0''':

<syntaxhighlight lang="bash">
git clone https://github.com/EttusResearch/uhd.git
cd uhd
git checkout v4.9.0.0
</syntaxhighlight>

Build and install UHD:

<syntaxhighlight lang="bash">
cd host
mkdir build && cd build
cmake ..
make -j$(nproc)
sudo make install
sudo ldconfig
export LD_LIBRARY_PATH=/usr/local/lib
sudo usrp_images_downloader
</syntaxhighlight>

Verify the installation:

<syntaxhighlight lang="bash">
uhd_usrp_probe
uhd_find_devices
</syntaxhighlight>

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

[[File:fae8d810-08f0-4ae3-ab87-5b6a31eeaa66.png|thumb|400px|center|uhd_usrp_probe output for B206]]
[[File:5026560b-fc07-4f77-953c-c17f41acfccc.png|thumb|400px|center|uhd_find_devices output for N310 and X410]]

'''Figure:''' Examples of UHD utilities used for USRP probing and device discovery.

=== Post UHD Installation Tasks ===
# '''Download USRP images'''
<syntaxhighlight lang="bash">
sudo /usr/local/bin/uhd_images_downloader
</syntaxhighlight>

# '''Add USB udev rule''' (can be limited to specific vendor/device IDs)
<syntaxhighlight lang="bash">
sudo nano /etc/udev/rules.d/99-usb.rules
# Add this line:
# SUBSYSTEM=="usb",MODE="0666"
sudo udevadm control --reload-rules
sudo udevadm trigger
</syntaxhighlight>

# Unplug and replug the USB device if it was already connected.

# '''Enable Python UHD API visibility'''
<syntaxhighlight lang="bash">
echo "/usr/local/lib/python3.10/site-packages" | \
sudo tee /usr/local/lib/python3.10/dist-packages/local-site-packages.pth
</syntaxhighlight>

=== UHD Installation Verification ===
# '''Find connected USRP devices'''
<syntaxhighlight lang="bash">
uhd_find_devices
</syntaxhighlight>

# '''Run throughput benchmark on the B2x0 device'''
<syntaxhighlight lang="bash">
/usr/local/lib/uhd/examples/benchmark_rate --args "type=b200" --rx_rate 10e6
</syntaxhighlight>

# '''Run Python throughput benchmark'''
<syntaxhighlight lang="bash">
python3.10 /usr/local/lib/uhd/examples/python/benchmark_rate.py --args "type=b200" --rx_rate 10e6
</syntaxhighlight>

== Installing and Configuring the USRP X410 Radio ==

For detailed documentation, see the official Ettus manual:
[https://files.ettus.com/manual/page_usrp_x4xx.html https://files.ettus.com/manual/page_usrp_x4xx.html]

=== Connecting to the X410 ===
You can connect to the USRP X410 using either of the following interfaces:
* Ethernet (RJ45)
* USB-C JTAG Console

If you cannot connect to the X410 (e.g., because it has a static IP address):

# Connect the USRP to your PC using a USB-C ↔ USB cable.
See the '''Serial connection''' section in the Ettus manual: [https://files.ettus.com/manual/page_usrp_x4xx.html]
# Change the static IP to a DHCP-assigned IP.
See the '''Network interfaces''' section: [https://files.ettus.com/manual/page_usrp_x4xx.html]

=== Updating the Filesystem ===
For full details, refer to the Ettus manual section: [https://files.ettus.com/manual/page_usrp_x4xx.html Updating Filesystems].

The easiest method is to perform the update directly on the X410 using the built-in <code>usrp_update_fs</code> utility:

<syntaxhighlight lang="bash">
# Login to the USRP
ssh root@usrp_ip

# Update filesystem to UHD 4.9
usrp_update_fs -t UHD-4.9

# Or install the UHD master version
usrp_update_fs -t master

# Reboot the USRP
reboot

# If the reboot works and the device is functional, commit the changes
mender commit
</syntaxhighlight>

=== Updating the FPGA Image ===
For details, see: [https://files.ettus.com/manual/page_usrp_x4xx.html Updating the FPGA].

You can verify and benchmark the X410 performance using the UHD example utility:

<syntaxhighlight lang="bash">
./benchmark_rate --args="mgmt_addr=10.89.12.177,addr=192.168.10.2,\
second_addr=192.168.11.2,clock_source=internal,time_source=internal" \
--rx_rate 200e6 --channels 0 --rx_channels 0
</syntaxhighlight>

== Installing Spectrum Sensing Example on x86 Architecture ==

This section provides a detailed procedure for installing and running the Spectrum Sensing example on an x86 architecture.
The '''spectrum_sensing''' folder within the NI-RF Data Recording API repository provides a ready-to-run demonstration of live RF spectrum sensing using a single receiver (e.g., USRP B206/X410) connected to an x86 host.

=== Setup Instructions ===
# '''Clone the repository:'''
<syntaxhighlight lang="bash">
git clone https://github.com/ni/ni-rf-data-recording-api.git
</syntaxhighlight>

# '''Clone the YOLOv5 repository:'''
<syntaxhighlight lang="bash">
git clone https://github.com/ultralytics/yolov5
</syntaxhighlight>

# '''Install dependencies for NI RF Data Recording API:'''
<syntaxhighlight lang="bash">
cd ni-rf-data-recording-api
pip install -r requirements.txt
</syntaxhighlight>

=== Python Package Dependencies ===
The following Python packages are required to run the spectrum sensing pipeline using the NI-RF Data Recording API.

* '''termcolor''' – Prints colored text in terminal for log readability.
* '''numpy (>=1.23.5, <2.0.0)''' – Core numerical library for IQ array operations, FFTs, and signal processing.
* '''scipy (>=1.4.1)''' – Used for filtering, spectral analysis, and mathematical routines.
* '''matplotlib (>=3.3)''' – Generates spectrum plots, spectrograms, and PSD visualizations.
* '''pandas (>=1.1.4)''' – Handles RF metadata and experiment logs.
* '''pyyaml (>=5.3.1)''' – Loads YAML configuration files for USRP setup parameters.
* '''nptdms''' – Enables reading and writing NI TDMS waveform files.
* '''sigmf''' – Implements Signal Metadata Format for storing IQ recordings with metadata.

# '''Install dependencies for the example:'''
<syntaxhighlight lang="bash">
cd ni-rf-data-recording-api/examples/spectrum_sensing
pip install -r requirements.txt
</syntaxhighlight>

=== Advanced Python Dependencies for Spectrum Sensing and ML Integration ===
These additional libraries enable advanced visualization, AI/ML inference, and web dashboard integration.

* '''dash''' – Web-based dashboard framework for real-time spectrum visualization.
* '''dash-daq''' – Adds instrumentation UI components for live control.
* '''dash-bootstrap-components''' – Provides responsive Bootstrap layouts for Dash apps.
* '''pillow (>=10.3.0)''' – Handles image saving and processing of spectrograms.
* '''torch (>=1.8.0)''' – PyTorch deep learning framework for inference/training.
* '''torchvision (>=0.9.0)''' – Vision utilities for preprocessing spectrograms.
* '''ultralytics (>=8.2.34)''' – YOLOv8 utilities for signal classification.
* '''gitpython (>=3.1.30)''' – Enables automated Git repository handling.
* '''opencv-python (>=4.1.1)''' – Performs spectrogram image manipulation.
* '''seaborn (>=0.11.0)''' – Provides data visualization and heatmaps.
* '''tqdm (>=4.66.3)''' – Adds progress bars during capture or inference.
* '''requests (>=2.32.2)''' – Handles model downloads and HTTP requests.
* '''setuptools (>=70.0.0, <80.9.0)''' – Ensures consistent Python packaging.

=== Configuring the Example ===
The configuration files are located at:
<code>~/ni-rf-data-recording-api/examples/spectrum_sensing/config/</code>

They define:
* RF parameters: center frequency, gain, bandwidth, sample rate
* Device type (e.g., B206) and connection interface
* Capture duration and number of records
* Output directory and naming conventions

=== Key Configuration Parameters ===
{| class="wikitable"
! Parameter !! Description !! Example
|-
| <code>rx_recorded_data_path</code> || Path to store captured IQ data || <code>datasets/records/</code>
|-
| <code>nrecords</code> || Number of snapshots to capture || <code>10</code>
|-
| <code>freq</code> || Center frequency (Hz) || <code>3.6e9</code>
|-
| <code>rate</code> || IQ sample rate (Sps) || <code>50e6</code>
|-
| <code>bandwidth</code> || Analog bandwidth || <code>20e6</code>
|-
| <code>gain</code> || RX gain (dB) || <code>40</code>
|-
| <code>duration</code> || Recording duration (s) || <code>0.04</code>
|-
| <code>rate_source</code> || Sample rate mode || <code>user_defined</code>
|-
| <code>captured_data_file_name</code> || Prefix for SigMF files || <code>rx-waveform-td-rec-</code>
|-
| <code>antenna</code> || Antenna port || <code>TX/RX</code>
|-
| <code>clock_reference</code> || Reference clock || <code>internal</code>
|}

=== Execution ===
(a) Run the UI application:
<syntaxhighlight lang="bash">
cd ~/ni-rf-data-recording-api/examples/spectrum_sensing
python spectrum_sensing.py
</syntaxhighlight>

After launching, you’ll see:
<code>Dash is running on http://127.0.0.1:8050/</code>
Open this link in your browser to access the dashboard.

* Load a configuration file from the dashboard.
* Click '''Start''' to begin sensing.
* IQ samples will be captured and saved in SigMF format at:
<code>~/ni-rf-data-recording-api/examples/spectrum_sensing/datasets/records</code>

[[File:Dashboard.png|thumb|800px|center|AI-based spectrum sensing dashboard using NI USRP SDRs and NI RF Data Recording API]]

'''Figure:''' AI-based spectrum sensing system using NI USRP SDRs, the NI RF Data Recording API, and a web-based control dashboard.

=== System Workflow Description ===
The figure above shows the end-to-end architecture for AI-driven spectrum sensing with NI USRPs.

* '''TX Configuration:''' User selects the waveform to transmit; it can be sent over-the-air or via RF cable.
* '''Start/Stop Control:''' Clicking '''Start''' launches the sensing and recording pipeline with live indicators for SDR initialization and capture status.

(b) Run the inference script:
<syntaxhighlight lang="bash">
cd ~/ni-rf-data-recording-api/examples/spectrum_sensing
python inference.py
</syntaxhighlight>

The inference script processes IQ recordings stored in:
<code>~/ni-rf-data-recording-api/examples/spectrum_sensing/datasets/records</code>

It converts each dataset into a spectrogram image saved at:
<code>~/ni-rf-data-recording-api/examples/spectrum_sensing/datasets/images</code>

The spectrograms are passed to a pre-trained '''YOLOv5''' model for signal classification.

[[File:inference_running.png|thumb|800px|center|YOLOv5-based live inference detecting a 5G NR signal with 96% confidence]]

'''Figure:''' Real-time inference output showing successful detection of a 5G NR waveform using a pre-trained YOLOv5 model.

=== Live Inference Visualization ===
After IQ samples are captured and stored, <code>inference.py</code> generates spectrograms and classifies signals.
In the shown example, the YOLOv5 model identifies a 5G NR waveform (<code>5GNR</code>) with a confidence score of '''0.96'''.
Detected signals show high classification accuracy and clear time-frequency boundaries.

== Spectrum Sensing Application with NI USRP and NVIDIA Jetson ==

This section summarizes the official documentation for running the <code>spectrum_sensing</code> application using NI USRP SDR hardware on NVIDIA Jetson platforms.

=== Overview ===
The application demonstrates real-time spectrum sensing by interfacing a NI USRP SDR (e.g., B206) with an NVIDIA Jetson device over USB 3.0. The Jetson hosts the NI RF Data Recording API and executes the entire data acquisition pipeline — including RF configuration, signal capture, visualization, and data formatting into SigMF files.
Because Jetson devices are ARM-based, a Jetson-specific PyTorch package is available from NVIDIA, while TorchVision must be built from source.

=== PyTorch Installation ===
# Install required dependencies:
<syntaxhighlight lang="bash">
sudo apt update
sudo apt install python3-pip libopenblas-base libopenmpi-dev
sudo pip3 install --upgrade pip
</syntaxhighlight>

# For Python 3.10 and JetPack 6.2.1, install PyTorch 2.5:
<syntaxhighlight lang="bash">
wget https://developer.download.nvidia.com/compute/redist/jp/v61/pytorch/torch-2.5.0a0+872d972e41.nv24.08.17622132-cp310-cp310-linux_aarch64.whl
pip3 install torch-2.5.0a0+872d972e41.nv24.08.17622132-cp310-cp310-linux_aarch64.whl
</syntaxhighlight>

# Fix libcusparse-related errors (if any):
<syntaxhighlight lang="bash">
mkdir -p ~/tmp_cusparselt && cd ~/tmp_cusparselt
wget https://developer.download.nvidia.com/compute/cusparselt/redist/libcusparse_lt/linux-aarch64/libcusparse_lt-linux-aarch64-0.7.0.0-archive.tar.xz

tar xf *.tar.xz
sudo cp -a libcusparse_lt-linux-aarch64-0.7.0.0-archive/include/* /usr/local/cuda/include/
sudo cp -a libcusparse_lt-linux-aarch64-0.7.0.0-archive/lib/* /usr/local/cuda/lib64/
sudo ldconfig
cd ~ && rm -rf ~/tmp_cusparselt

# Verify installation
python3 -c "import torch; print(torch.__version__); print(torch.cuda.is_available())"
# Output should show:
# 2.5.0a0+872 and True
</syntaxhighlight>

=== PyTorch Vision (torchvision) ===
# Install dependencies:
<syntaxhighlight lang="bash">
sudo apt-get install libjpeg-dev zlib1g-dev libpython3-dev libopenblas-dev \
libavcodec-dev libavformat-dev libswscale-dev
</syntaxhighlight>

# Clone the source repository:
<syntaxhighlight lang="bash">
git clone --branch v0.20.0 https://github.com/pytorch/vision.git
</syntaxhighlight>

# Build and install:
<syntaxhighlight lang="bash">
cd vision
export BUILD_VERSION=0.20.0
python3 setup.py build
python3 setup.py install
</syntaxhighlight>

=== Python Virtual Environment (Optional) ===
To isolate the working environment from the system:
# Install <code>venv</code> support:
<syntaxhighlight lang="bash">
sudo apt-get install python3.10-venv
</syntaxhighlight>

# Create and activate environment:
<syntaxhighlight lang="bash">
python3.10 -m venv .venv --system-site-packages --prompt demo
source .venv/bin/activate
</syntaxhighlight>

=== Python Requirements ===
# Install SigMF:
<syntaxhighlight lang="bash">
pip install sigmf
</syntaxhighlight>

# Install npTDMS:
<syntaxhighlight lang="bash">
pip install npTDMS
</syntaxhighlight>

# Colored terminal output:
<syntaxhighlight lang="bash">
pip install colored termcolor
</syntaxhighlight>

# Dash and dashboard components:
<syntaxhighlight lang="bash">
pip install dash dash_daq dash_bootstrap_components
</syntaxhighlight>

# YOLOv5 pre-requirements:
<syntaxhighlight lang="bash">
pip install -U "gitpython>=3.1.30" "matplotlib>=3.3" "numpy>=1.23.5" \
"opencv-python>=4.1.1" "pillow>=10.3.0" psutil "PyYAML>=5.3.1" \
"requests>=2.32.2" "scipy>=1.4.1" "thop>=0.1.1" "tqdm>=4.66.3" \
"ultralytics>=8.2.34" "setuptools>=70.0.0" "seaborn>=0.11.0"
</syntaxhighlight>

=== YOLOv5 Model ===
The demo application uses the YOLOv5 image detection model from Ultralytics (AGPL-3.0 license).

<syntaxhighlight lang="bash">
git clone https://github.com/ultralytics/yolov5
</syntaxhighlight>

=== Demo Code and Data Recording API ===
Clone the NI RF Data Recording API repository:
<syntaxhighlight lang="bash">
git clone https://github.com/ni/ni-rf-data-recording-api.git
</syntaxhighlight>

After all dependencies are installed, the Spectrum Sensing use case can be executed on Jetson following the same procedure as described for the x86 system.

== Waveform Creation and Signal Recording Pipeline ==

This section outlines the process for generating waveforms, capturing RF data using the NI-RF Data Recording API, and producing spectrogram images for machine learning applications.

=== Waveform Repository ===
The <code>src/waveforms/</code> directory contains all pre-generated test signals used with the NI RF Data Recording API.
It includes four subfolders: '''5G NR''', '''LTE''', '''Wi-Fi''', and '''Radar'''.

Each waveform consists of:
* '''IQ Data File''' (<code>.tdms</code> or <code>.mat</code>) — contains complex baseband samples.
* '''Configuration File''' (<code>.rfws</code>, <code>.yaml</code>, or <code>.csv</code>) — describes waveform parameters such as bandwidth and sampling rate.

'''Examples:'''
* LTE: <code>LTE_TDD_DL_20MHz_....tdms</code> + <code>...rfws</code>
* Radar: <code>Radar_Waveform_BW_2M.mat</code> + <code>Radar_Waveform_BW_2M.yaml</code>

[[File:waveform_repository_small_dimensions.png|thumb|800px|center|Waveform repository flow]]

'''Figure:''' Waveform repository structure showing pre-generated 5G NR, LTE, Wi-Fi, and Radar signals mapped through the Wireless Link Parameter Dictionary.

=== Waveform Sources ===
* '''RFmx Waveform Creator:''' Used for generating 5G NR and LTE waveforms (<code>.tdms</code> + <code>.rfws</code>).
* '''IEEE MATLAB Wi-Fi Generator:''' Used for Wi-Fi test signals (<code>.mat</code> + <code>.csv</code>).
* '''Simulated Radar Generator (MATLAB):''' Used for radar signals (<code>.mat</code> + <code>.yaml</code>).

=== Usage in the API ===
During recording, JSON/YAML configuration files in <code>src/config/</code> reference these waveform paths.
The <code>wireless_link_parameter_map.yaml</code> dictionary maps waveform configuration fields (e.g., bandwidth, sampling rate, standard) to the SigMF metadata format — ensuring standardized dataset descriptions.

=== Recording IQ Data and Metadata via API ===
Once waveforms are prepared:

# Edit the configuration file (YAML/JSON) with your TX/RX parameters such as frequency, gain, and waveform paths.
# Run the recording:
<syntaxhighlight lang="bash">
python3 main_rf_data_recording_api.py --config path/to/your_config.yaml
</syntaxhighlight>
# The API maps parameters to SigMF metadata, controls USRP Tx/Rx via UHD, and writes:
** <code>.sigmf-data</code> (binary IQ samples)
** <code>.sigmf-meta</code> (JSON metadata)

=== Spectrogram Image Generation via Preprocessing ===
After dataset generation:

* Run preprocessing scripts (e.g., <code>rf_data_pre_processing_plot.py</code>) to visualize or convert SigMF recordings into time/frequency plots.
* Generate and crop spectrograms, partitioning them into training and validation sets for ML workflows.
* The structured image datasets form the foundation for AI-based spectrum classification and detection.

This end-to-end pipeline — from waveform generation to SigMF-formatted capture and spectrogram creation — enables reproducible, metadata-rich dataset production for AI-driven spectrum sensing research.

== How to use RF Data Recording API with user defined dataset? ==
To use the NI RF Data Recording API with a user-defined dataset for training and inference using YOLOv8, follow this multi-step process covering signal generation, data preprocessing, model training, and inference.

---

=== SigMF Data and Metadata Generation ===
Once the transmission signal is configured, stream IQ samples and record them in '''SigMF''' format by running <code>data_recording.py</code>:

* Location of the script:
: <code>/ni-rf-data-recording-api/examples/spectrum_sensing</code>

* SigMF outputs:
** <code>.sigmf-data</code>: Binary file with raw IQ samples.
** <code>.sigmf-meta</code>: JSON metadata (frequency, sample rate, gain, antenna, timestamps, etc.).

The script uses your YAML/JSON control file for parameters (center frequency, sample rate, bandwidth, gain, capture duration, number of records).

* Output directory:
: <code>/ni-rf-data-recording-api/examples/spectrum_sensing/datasets/records</code>

These SigMF files become the primary dataset for later analysis, visualization, and ML-based classification (e.g., spectrogram-based YOLO).

---

=== Spectrogram Generation and Dataset Preprocessing ===
Convert SigMF recordings into labeled spectrogram images using <code>pre-processing.py</code>. It orchestrates:

# <code>spectrogram_creator.py</code> – Reads <code>.sigmf-data</code>, applies STFT, saves spectrogram images (e.g., in <code>datasets/images</code>).
# <code>image_cropper.py</code> – Removes non-signal plot artifacts (axes, labels, borders) to produce clean images for detection models.
# <code>dataset_partitioner.py</code> – Splits dataset into train/val (e.g., 80/20) with balanced classes.
# <code>label_maker.py</code> – Creates YOLO-compatible label files for each image in the format:
: <code><class_id> <x_center> <y_center> <image_width> <image_height></code>

'''Resulting structure:'''
* Cleaned spectrogram images: <code>datasets/images</code>
* YOLO labels: <code>datasets/labels</code>
* Splits: <code>datasets/train</code>, <code>datasets/val</code>

This pipeline yields a model-ready dataset for accurate training and inference.

---

=== Dataset Configuration: <code>data.yaml</code> for YOLO Training ===
'''Fields:'''
* <code>train</code> – Path to training images
* <code>val</code> – Path to validation images
* <code>nc</code> – Number of classes
* <code>names</code> – List of class names in class-id order

'''Example:'''
<syntaxhighlight lang="yaml">
train: datasets/train/images
val: datasets/val/images

nc: 3
names: ['5gnr', 'wifi', 'lte']
</syntaxhighlight>

Use this file with YOLOv5/YOLOv8 training commands. Store it in the project root or inside the dataset folder.

---

=== Model Training Using YOLOv8 (Example) ===

==== Cloning YOLOv8 from Source ====
<syntaxhighlight lang="bash">
# Clone Ultralytics YOLOv8
git clone https://github.com/ultralytics/ultralytics.git
cd ultralytics

# (Optional) Virtual environment
python3 -m venv .venv
source .venv/bin/activate # Linux/macOS
# .venv\Scripts\activate # Windows PowerShell

# Install in editable mode
pip install --upgrade pip
pip install -e .
</syntaxhighlight>

Verify:
<syntaxhighlight lang="bash">
yolo help
</syntaxhighlight>

==== YOLOv8 Training Command ====
Train the nano model on your spectrogram dataset:
<syntaxhighlight lang="bash">
yolo detect train \
model=yolov8n.pt \
data=/content/dataset/data.yaml \
epochs=50 \
imgsz=640 \
batch=16 \
project=burst_train \
name=yolov8n_spectrogram
</syntaxhighlight>

'''Parameter notes:'''
* <code>model=yolov8n.pt</code> – Base architecture (nano).
* <code>data=...</code> – Path to <code>data.yaml</code>.
* <code>epochs=50</code> – Training epochs.
* <code>imgsz=640</code> – Input resolution.
* <code>batch=16</code> – Batch size.
* <code>project</code>/<code>name</code> – Output directories for logs/artifacts.

'''Outputs:'''
: <code>burst_train/yolov8n_spectrogram</code>
(Weights, logs, confusion matrices, PR curves, etc.)

== Conclusion ==
The NI RF Data Recording API provides a powerful and flexible framework for real-time spectrum sensing, dataset generation, and AI-driven signal classification across both x86 and embedded platforms such as NVIDIA Jetson.
By leveraging standardized formats like SigMF and integrating deep learning models such as YOLOv8, the framework enables a complete end-to-end workflow—from RF signal acquisition and metadata tagging to spectrogram creation, training, and live inference.

This modular approach allows researchers and engineers to rapidly prototype, evaluate, and deploy intelligent wireless sensing systems that bridge the gap between traditional SDR experimentation and modern AI-based spectrum analytics.
The same unified methodology can be extended to multi-band sensing, interference detection, cognitive radio, and 6G spectrum intelligence research, ensuring scalability and reproducibility in both laboratory and field environments.

[[Category:Application Notes]]

File:waveform repository small dimensions.png

2025-11-05T12:32:49Z

NeelPandeya:

AI-Based Spectrum Sensing with Nvidia Jetson and USRP

2025-11-05T12:30:01Z

NeelPandeya: /* Key Configuration Parameters */

AI-Based Spectrum Sensing with Nvidia Jetson and USRP

2025-11-05T12:21:22Z

NeelPandeya: /* Waveform Creation and Signal Recording Pipeline */

== Application Note Number and Authors ==

'''AN-811'''

== Authors ==

Bharat Agarwal and Neel Pandeya

== Executive Summary ==

This application note presents a complete framework for real-time spectrum sensing using NI Universal Serial Radio Peripheral (USRP) Software-Defined Radios (SDRs) and NVIDIA Jetson or standard x86 compute platforms. The framework is not limited to a single USRP model—the X410, X310, and B2xx series (e.g., B206) can all be used as transmitters or receivers depending on the deployment scenario. The solution leverages the NI-RF Data Recording API to enable scalable RF data acquisition, SigMF-compliant metadata tagging, and seamless integration with machine learning workflows.

The document outlines three core usage scenarios:

# x86-Based Development Workflow: Using a workstation or server-class x86 machine, paired with high-end USRPs such as the X410 or X310, the system supports wideband spectrum sensing (up to 400 MHz instantaneous bandwidth per channel). This configuration is ideal for laboratory development, algorithm training, and high-throughput dataset generation.
# Jetson-Based Embedded Sensing (Primary Use Case): Using an NVIDIA Jetson platform as the host (e.g., AGX Orin) with a compact B206 SDR as receiver and an X410 as transmitter, the system delivers efficient edge inference with GPU acceleration. Although the B206 limits the instantaneous bandwidth to 56 MHz, this configuration emphasizes portability, low power, and real-time embedded operation.
# User-Defined Dataset Integration: In addition to live spectrum sensing, the framework supports integration and generation of user-defined datasets. This functionality extends the applicability of the system beyond real-time capture, enabling flexible experimentation, reproducibility, and seamless AI/ML dataset preparation. Two complementary capabilities are supported:
## SigMF Dataset Recording
##* All captured RF data is stored in the Signal Metadata Format (SigMF).
##* SigMF pairs raw IQ samples (<code>.sigmf-data</code>) with a corresponding metadata file (<code>.sigmf-meta</code>) in JSON format.
##* Metadata describes acquisition parameters such as frequency, bandwidth, gain, device type, timestamps, and scenario context.
##* Being human-readable and portable, SigMF datasets can be used across a wide range of software environments, making them ideal for wireless research, spectrum monitoring, AI/ML training for 6G, and regulatory validation.
##* Example: A spectrum sensing session at 3.5 GHz, 20 MHz bandwidth, and 10-second duration will result in a SigMF-compliant dataset ready for further processing or ML-based classification.
## Continuous Waveform Playback with User-Defined Files
##* The platform supports continuous transmission and replay of user-defined waveforms in TDMS or MATLAB (.mat) formats.
##* This allows testing with standard-compliant signals such as 5G NR, LTE, Radar, or Wi-Fi, or custom-designed waveforms.
##* By replaying predefined waveforms, researchers can benchmark algorithms, validate coexistence scenarios, and reproduce experiments consistently across testbeds.
##* Example: A MATLAB-generated LTE downlink frame can be continuously transmitted via an X410 while a B206 or X310 records the received signal in SigMF format for classification.

Together, these capabilities ensure that the NI-RF Data Recording API can handle both dataset creation (SigMF-based recording) and waveform-driven experimentation (TDMS/MAT playback), thereby covering the entire pipeline from signal generation to ML-ready dataset production.

By combining NI's reliable SDR hardware with NVIDIA's efficient edge compute platforms and a unified data interface, this solution supports a wide range of spectrum intelligence applications—from interference detection and dynamic spectrum access to embedded RF analytics. The methodology enables scalable deployment from lab to field, supporting real-time insights and long-term data collection in a streamlined, modular pipeline.

== USRP B206 Overview ==

[[File: USRP-b206_mini_01.jpg|thumb|center|400px|NI USRP B206 Software Defined Radio]]

The USRP B206 is a compact, low-cost SDR developed by NI / Ettus Research. It supports full-duplex operation with one transmit and one receive channel, making it ideal for a variety of wireless communication and sensing applications. The B206 covers a wide RF frequency range from 70 MHz to 6 GHz and supports up to 56 MHz of instantaneous bandwidth. This makes it suitable for applications such as spectrum sensing, dynamic spectrum access, and cognitive radio.

The device connects to a host system via a high-speed USB 3.0 interface, which enables data rates sufficient for wideband real-time signal acquisition and transmission. It also supports USB 2.0 with reduced performance. The B206 includes a Xilinx Spartan-6 FPGA for onboard signal processing and is powered either through USB or an external DC supply, the latter being preferred for optimal RF performance.

The USRP B206 is compatible with both x86 and ARM-based hosts, including embedded platforms like the NVIDIA Jetson series. This enables portable and energy-efficient deployment of spectrum sensing pipelines at the network edge. It is fully supported by the open-source UHD and integrates with popular SDR development tools such as GNU Radio, MATLAB, and LabVIEW.

Typical use cases for the B206 include real-time spectrum monitoring, wireless signal classification using machine learning, prototyping of 4G/5G systems, and SDR education and training. Its compact size and flexible software support make it an excellent choice for both laboratory research and embedded field deployments.

'''Key Features of the USRP B206:'''
* RF Capabilities: 1 TX, 1 RX, independently tunable, RF transceiver, 70 MHz to 6 GHz, up to 56 MHz bandwidth
* Programmable Logic: FPGA: Xilinx Spartan-6 XC6SLX150
* Software: UHD 4.9 or later, GNU Radio, C/C++ and Python
* Synchronization: REF (external 10 MHz or PPS reference)
* Digital Interfaces: USB 3.0, GPIO (8 I/O lines with 3.3 V I/O voltage), and JTAG
* Power, form factor: 5 V DC, 0.9 A maximum; Board-only: 84.3 mm × 51.0 mm × 8.7 mm; Enclosed: 84.9 mm × 55.7 mm × 19.8 mm

== NI-RF Data Recording API Overview ==

The '''[https://github.com/ni/ni-rf-data-recording-api/blob/main/README.md NI-RF Data Recording API]''' is an open-source, Python-based framework developed by National Instruments (NI) in collaboration with the Genesys Lab at Northeastern University. It is designed to streamline RF data collection using NI USRP SDRs, with support for structured metadata via the '''[https://github.com/sigmf/SigMF Signal Metadata Format (SigMF)]'''.

=== Purpose and Scope ===
This API enables efficient recording, labeling, and replay of real-world RF signals. It is particularly suited for generating datasets used in AI/ML workflows, wireless research, and spectrum monitoring. The framework abstracts low-level UHD interactions, allowing users to define RF parameters through JSON or YAML configuration files.

=== Key Features ===
* Support for both signal transmission and reception using NI USRP hardware.
* Native recording in SigMF format, capturing both IQ samples and rich metadata.
* Python-based, modular architecture supporting custom extensions and automation.
* Multi-SDR support via coordinated configuration files.
* Sample waveform libraries included (e.g., LTE, NR, radar, Wi-Fi) in TDMS/MAT formats.
* Utility scripts for standalone use: transmit, receive, replay, or continuous capture.

=== System Requirements ===
The API has been validated on Ubuntu 22.04 systems with the following dependencies:
* At least one compatible NI USRP device (e.g., B206, X310, X410).
* Installed UHD drivers with Python bindings.
* Python 3.x and required libraries (e.g., NumPy, PyYAML).
* Optional Docker environment for containerized deployment.

=== Relevance to Our Use Cases ===
In this application note, we explore three deployment scenarios of the NI-RF Data Recording API:

# x86-based Spectrum Sensing: Using the API on a desktop or server-class system, the USRP B206 is configured to perform spectrum capture, and the data is saved in SigMF format. This setup is optimal for high-throughput and lab-based development environments.
# Embedded Jetson Platform: The API is deployed on an NVIDIA Jetson device interfaced with the USRP B206 over USB 3.0. This enables compact, power-efficient, and real-time spectrum sensing at the edge. Onboard GPU resources are leveraged for FFT computation and ML inference.
# User-Defined Dataset Integration: The API provides flexible support for user-defined datasets through two complementary capabilities:
## Importing Pre-Generated Data: Users can seamlessly import and tag custom IQ recordings (e.g., SigMF-compliant files or previously captured spectrum data) into the repository. This enables integration of external datasets for benchmarking, anomaly detection, or reproducible research.
## Data Lake Storage for AI/ML Pipelines: All captured and imported datasets can be stored in a structured data lake, significantly simplifying automated dataset selection, management, and preprocessing. This facilitates streamlined workflows for AI/ML model design, training, and validation in spectrum sensing and 6G wireless research.

The NI-RF Data Recording API provides a flexible, hardware-agnostic foundation for both live RF capture and offline dataset handling, making it central to spectrum intelligence and edge-aware signal processing workflows.

== Reference Architecture for Spectrum Sensing ==

To support flexible and scalable RF data collection workflows, we propose a dual-mode reference architecture that demonstrates spectrum sensing using NI USRP hardware with two compute platforms: a high-performance x86 host and an embedded NVIDIA Jetson device. Both configurations utilize the NI-RF Data Recording API to capture, store, and manage RF data in SigMF format. The hardware setup supports real-time signal acquisition, tagging, and streaming for downstream machine learning or signal intelligence tasks.

=== x86-Based High-Performance Architecture ===

[[File: x86.png|thumb|center|900px|x86-based spectrum sensing architecture using NI USRP B206 and X410]]

In this high-performance lab-based deployment, a desktop-class x86 host system is used. The USRP X410 (or alternatively the X310) serves as the receiver, connected to the workstation via a 10 GbE Ethernet interface to support high-throughput data streaming. The transmitter is also an NI USRP X410, connected through a 10 GbE link via a network switch. A 30 dB attenuator is inserted between the TX and RX paths to protect the RF front-end from saturation during close-proximity transmission.

This configuration demonstrates the full high-performance capability of the platform, enabling wideband spectrum sensing and scalable data capture.

Host System Specifications:
* Operating System: Ubuntu 22.04
* UHD Compatibility: The NI-RF Data Recording API supports UHD ≥ 4.2. Most devices such as the X410 or X310 work with older versions, but the B206 requires UHD ≥ 4.9.
* Processor: Intel Xeon w7-2495X (24 cores, 2.5 GHz)

This setup is suited for '''high-throughput spectrum recording, algorithm development, and dataset generation''' in a lab environment. It offers large storage capacity, stable power, and CPU-intensive post-processing capabilities.

=== Jetson-Based Embedded Architecture ===

[[File:SS_with_x86.png|thumb|center|900px|Jetson-based spectrum sensing architecture using NI USRP B2x0 and X410]]

In this configuration, an NVIDIA Jetson module serves as the edge processing unit. The Jetson connects to a USRP B2x0 (e.g., B206) over a USB 3.0 interface, acting as the spectrum sensor (receiver). A USRP X410 acts as the transmitter, linked via a LAN switch. A 30 dB attenuator is used between the TX and RX paths to prevent RF front-end saturation during close-proximity transmission.

The Jetson executes the RF data acquisition pipeline and leverages onboard GPU resources to perform high-speed FFTs, signal classification, and real-time metadata tagging. A display, keyboard, and mouse connect directly for standalone operation.

'Jetson System Specifications:
* Operating System: Ubuntu 22.04 with JetPack 6.2.1
* UHD Version: 4.9
* Processor: NVIDIA Jetson AGX Orin 64 GB

This configuration is ideal for low-power, field-deployable sensing nodes where edge inference, minimal latency, and portability are required. The NI-RF Data Recording API runs natively on ARM-based Jetson, ensuring consistent data acquisition across architectures.

=== Common Features Across Architectures ===
Both architectures support:
* Real-time IQ sample recording and metadata tagging using NI-RF Data Recording API
* Integration with SigMF-compliant datasets
* Wideband RF capture across 70 MHz–6 GHz (with B206)
* Configurable gain, center frequency, bandwidth, and LO offsets via JSON/YAML files

The dual-platform design allows researchers to prototype, validate, and deploy spectrum sensing pipelines in a variety of scenarios—from power-constrained edge sensing to scalable, cloud-connected research environments.

== Bill of Materials ==

This section lists the hardware and software components required to replicate the spectrum sensing setup described in the reference architectures.

=== Jetson-Based Embedded Spectrum Sensing Setup ===
* '''NI USRP B206 SDR (Receiver)'''
** Frequency Range: 70 MHz – 6 GHz
** Bandwidth: up to 56 MHz
** Interface: USB 3.0

* '''NI USRP X410 SDR (Transmitter)'''
** Frequency Range: up to 7.2 GHz
** Bandwidth: up to 1 GHz per channel
** Interface: 10 GbE (SFP+)

* '''NVIDIA Jetson AGX Orin 64 GB Developer Kit (Edge Host)'''
** GPU: 2048-core Ampere GPU
** Interfaces: USB 3.0, 10 Gb Ethernet
** OS: Ubuntu 22.04 (ARM64) with JetPack 6.2.1

* '''Display and Input Devices'''
** Monitor (DisplayPort or HDMI)
** USB Keyboard and Mouse

* '''30 dB RF Attenuator'''
** Protects RX frontend during loopback or close-range transmission

* '''Network Switch (Gigabit)'''
** Routes LAN traffic between Jetson and X410

* '''RF Cables and Antennas or Dummy Load'''
* '''Power Supply for USRP X410 and Jetson'''
* '''USB 3.0 Cable (for Jetson–B206 interface)'''

=== x86-Based Spectrum Sensing Setup ===
* '''NI USRP B206 SDR (Receiver)'''
* '''NI USRP X410 SDR (Transmitter)'''
* '''x86 Workstation or Server (Host PC)'''
** CPU: Intel Xeon w7-2495X, 24 cores, 2.5 GHz
** OS: Ubuntu 22.04 LTS
** UHD: Version 4.8 or newer
** RAM: Minimum 32 GB recommended
** Storage: SSD for high-speed IQ data logging

* '''Display and Input Devices'''
** Monitor (DisplayPort or HDMI)
** USB Keyboard and Mouse

* '''30 dB RF Attenuator'''
* '''USB 3.0 Cable (PC–B206 interface)'''
* '''Ethernet Cables (PC and X410 to switch)'''
* '''Network Switch (Gigabit or 10 GbE)'''
* '''Coaxial Cable (RF connection between TX and RX)'''

=== Software Requirements (Common) ===
* '''NI-RF Data Recording API'''
** GitHub: [https://github.com/ni/ni-rf-data-recording-api https://github.com/ni/ni-rf-data-recording-api]
** Supports SigMF format, YAML/JSON configuration, UHD interface

* '''UHD (USRP Hardware Driver)'''
** Version 4.9 recommended
** Installed natively

* '''Python 3.x Environment'''
** Required packages: numpy, pyyaml, sigmf, uhd, etc.

== Hardware Requirements ==

To implement the proposed spectrum sensing architecture, the following hardware components are required. The selected devices are chosen for their compatibility with the NI-RF Data Recording API, support for UHD drivers, and ability to perform high-speed RF acquisition and processing.

=== NI USRP B206 (Receiver SDR) ===
The USRP B206 is a low-cost, full-duplex software-defined radio with wide RF coverage and USB 3.0 connectivity, making it ideal for spectrum sensing tasks.

* '''Frequency Range:''' 70 MHz – 6 GHz
* '''Bandwidth:''' Up to 56 MHz
* '''Interface:''' USB 3.0
* '''Form Factor:''' Compact, bus-powered or DC-powered
* '''Purchase Link:''' [https://www.ettus.com/all-products/usrp-b200/ https://www.ettus.com/all-products/usrp-b200/]

=== NI USRP X410 (Transmitter SDR) ===
The USRP X410 is a high-performance, 4-channel SDR capable of wideband signal transmission and reception. It supports 10 GbE connectivity and real-time FPGA processing.

* '''Frequency Range:''' Up to 7.2 GHz
* '''Bandwidth:''' Up to 1 GHz per channel
* '''Interface:''' 10 GbE (SFP+), PCIe (optional)
* '''FPGA:''' Xilinx Zynq Ultrascale+ RFSoC
* '''Purchase Link:''' [https://www.ettus.com/all-products/usrp-x410/ https://www.ettus.com/all-products/usrp-x410/]

=== NVIDIA Jetson AGX Orin 64 GB Developer Kit (Edge Host) ===
The Jetson AGX Orin series provides a powerful embedded GPU platform for edge AI and RF signal processing.

* '''GPU:''' NVIDIA Ampere architecture
* '''RAM:''' 32 GB / 64 GB LPDDR4/5
* '''Connectivity:''' USB 3.0, Ethernet, GPIO
* '''OS Support:''' Ubuntu 20.04 / 22.04 (ARM64)
* '''Purchase Link:''' [https://store.nvidia.com/jetson/store/ https://store.nvidia.com/jetson/store/]

=== Network Switch (Gigabit or 10 GbE) ===
A managed or unmanaged Ethernet switch is required to route LAN traffic between the Jetson or x86 host and the USRP X410.

* '''Recommended:''' Netgear GS108, Mikrotik CRS305, or Cisco CBS350
* '''Typical Ports:''' 8+ (Gigabit or 10 GbE SFP+)
* '''Example Link:''' [https://www.netgear.com/business/wired/switches/smart/gs108/ https://www.netgear.com/business/wired/switches/smart/gs108/]

=== High-Performance x86 Host (Optional for Lab Use) ===
An x86 workstation is recommended for development, high-throughput data collection, or as an alternative to Jetson in a lab environment.

* '''Processor:''' Minimum specification of an 8-core CPU at 3 GHz or higher (e.g., Intel Xeon or equivalent). Higher core counts (e.g., 24-core Xeon W7-2495X) can improve throughput and parallel data processing but are not mandatory.
* '''RAM:''' 64 GB or more
* '''Storage:''' NVMe SSD for high-speed data logging
* '''Operating System:''' Ubuntu 22.04 LTS
* '''Form Factor:''' Tower workstation or server

=== RF Accessories ===
* '''RF Coaxial Cables (SMA)'''
* '''30 dB Attenuator''' – Protects RX during close TX–RX loopback tests
* '''Antennas''' (Wideband or band-specific)
* '''Dummy Load''' (for isolated lab TX tests)
* '''USB 3.0 Cable''' (for USRP B206)
* '''Ethernet Cables''' (Cat 6 or SFP+ DAC for X410)
* '''Power Supplies:'''
** Jetson: 19 V / 4.74 A adapter (usually included)
** X410: External DC or rack supply per specifications

== Software Requirements ==

This section outlines the required software components for enabling spectrum sensing using the NI-RF Data Recording API with USRP B206/X410 and NVIDIA Jetson or x86 hosts. These tools are compatible across both embedded and desktop-class platforms and support real-time signal acquisition and metadata tagging in SigMF format.

=== Ubuntu Operating System ===
* '''Version:''' Ubuntu 22.04 LTS (Jetson) / Ubuntu 22.04 LTS (x86 recommended)
* '''Download Link:''' [https://ubuntu.com/download https://ubuntu.com/download]
* '''Jetson OS Image:''' JetPack SDK includes Ubuntu and NVIDIA drivers
* '''JetPack Link:''' [https://developer.nvidia.com/embedded/jetpack https://developer.nvidia.com/embedded/jetpack]

=== NI-RF Data Recording API ===
* '''Description:''' Open-source Python API developed by NI and the Genesys Lab (Northeastern University) for recording and labeling RF data in SigMF format using USRP devices.
* '''Features:''' Configurable YAML/JSON setups, multi-SDR coordination, SigMF conversion, supports transmission/reception workflows.
* '''Repository:''' [https://github.com/ni/ni-rf-data-recording-api https://github.com/ni/ni-rf-data-recording-api]

=== UHD – USRP Hardware Driver ===
* '''Description:''' The official driver and API library for controlling and interfacing with all NI/Ettus USRP SDR hardware. Required for low-level communication between Python and the hardware.
* '''Version:''' The NI-RF Data Recording API requires a UHD version that supports the selected USRP device:
** For X410 (and other X-Series): UHD ≥ 4.2 (first stable release UHD 4.4 recommended)
** For B206: UHD ≥ 4.9 required
* '''Repository:''' [https://github.com/EttusResearch/uhd https://github.com/EttusResearch/uhd]
* '''Install Guide:''' [https://kb.ettus.com/Building_and_Installing_the_USRP_Open-Source_Toolchain_(UHD_and_GNU_Radio)_on_Linux UHD and GNU Radio Install Guide]

=== Python Environment ===
* '''Version:''' Python 3.10.12 or newer
* '''Required Packages:'''
** <code>numpy</code>, <code>pyyaml</code>, <code>sigmf</code>, <code>uhd</code>, <code>scipy</code>, <code>matplotlib</code>, etc.
* '''Package Manager:''' <code>pip</code> or <code>conda</code>
* '''Recommended Setup:''' Create a Python virtual environment for isolation and reproducibility.
* '''Download Link:''' [https://www.python.org/ https://www.python.org/]

=== SigMF Library (Python) ===
* '''Description:''' Used for generating and parsing metadata in the Signal Metadata Format (SigMF), enabling dataset interoperability and ML dataset labeling.
* '''Supported Version:''' Validated with '''SigMF 1.0.0''' (later versions such as 1.1.x or 1.2.x introduce major changes and have not been validated).
* '''Repository:''' [https://github.com/gnuradio/sigmf-numpy https://github.com/gnuradio/sigmf-numpy]
* '''Installation Command:''' <code>pip install sigmf==1.0.0</code>
* '''Reference:''' For more details, see the [https://github.com/ni/ni-rf-data-recording-api/tree/main/docs NI RF Data Recording API Getting Started Guide].

== Installing and Configuring the UHD Software ==

This section explains how to build and install the USRP Hardware Driver (UHD) from source code. At the time of this writing, the recommended version is '''UHD 4.9'''.

* It is strongly recommended to build UHD from source rather than installing from binary packages to ensure compatibility and access to the latest updates.
* For x86/64 Ubuntu systems with released UHD versions available, you may install via APT Debian packages.
* For Jetson (ARM64) systems, UHD must be built from source since no binary packages are provided.

---

Before building UHD, install all required dependencies (Ubuntu 22.04):

'''Note:''' If your system already has another UHD version installed, remove it first:

<syntaxhighlight lang="bash">
sudo apt remove libuhd* uhd-host
sudo rm -rf /usr/lib/uhd /usr/include/uhd /usr/local/lib/uhd /usr/local/include/uhd
</syntaxhighlight>

Then install build dependencies:

<syntaxhighlight lang="bash">
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
</syntaxhighlight>

Clone the UHD repository and check out version '''v4.9.0.0''':

<syntaxhighlight lang="bash">
git clone https://github.com/EttusResearch/uhd.git
cd uhd
git checkout v4.9.0.0
</syntaxhighlight>

Build and install UHD:

<syntaxhighlight lang="bash">
cd host
mkdir build && cd build
cmake ..
make -j$(nproc)
sudo make install
sudo ldconfig
export LD_LIBRARY_PATH=/usr/local/lib
sudo usrp_images_downloader
</syntaxhighlight>

Verify the installation:

<syntaxhighlight lang="bash">
uhd_usrp_probe
uhd_find_devices
</syntaxhighlight>

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

[[File:fae8d810-08f0-4ae3-ab87-5b6a31eeaa66.png|thumb|400px|center|uhd_usrp_probe output for B206]]
[[File:5026560b-fc07-4f77-953c-c17f41acfccc.png|thumb|400px|center|uhd_find_devices output for N310 and X410]]

'''Figure:''' Examples of UHD utilities used for USRP probing and device discovery.

=== Post UHD Installation Tasks ===
# '''Download USRP images'''
<syntaxhighlight lang="bash">
sudo /usr/local/bin/uhd_images_downloader
</syntaxhighlight>

# '''Add USB udev rule''' (can be limited to specific vendor/device IDs)
<syntaxhighlight lang="bash">
sudo nano /etc/udev/rules.d/99-usb.rules
# Add this line:
# SUBSYSTEM=="usb",MODE="0666"
sudo udevadm control --reload-rules
sudo udevadm trigger
</syntaxhighlight>

# Unplug and replug the USB device if it was already connected.

# '''Enable Python UHD API visibility'''
<syntaxhighlight lang="bash">
echo "/usr/local/lib/python3.10/site-packages" | \
sudo tee /usr/local/lib/python3.10/dist-packages/local-site-packages.pth
</syntaxhighlight>

=== UHD Installation Verification ===
# '''Find connected USRP devices'''
<syntaxhighlight lang="bash">
uhd_find_devices
</syntaxhighlight>

# '''Run throughput benchmark on the B2x0 device'''
<syntaxhighlight lang="bash">
/usr/local/lib/uhd/examples/benchmark_rate --args "type=b200" --rx_rate 10e6
</syntaxhighlight>

# '''Run Python throughput benchmark'''
<syntaxhighlight lang="bash">
python3.10 /usr/local/lib/uhd/examples/python/benchmark_rate.py --args "type=b200" --rx_rate 10e6
</syntaxhighlight>

== Installing and Configuring the USRP X410 Radio ==

For detailed documentation, see the official Ettus manual:
[https://files.ettus.com/manual/page_usrp_x4xx.html https://files.ettus.com/manual/page_usrp_x4xx.html]

=== Connecting to the X410 ===
You can connect to the USRP X410 using either of the following interfaces:
* Ethernet (RJ45)
* USB-C JTAG Console

If you cannot connect to the X410 (e.g., because it has a static IP address):

# Connect the USRP to your PC using a USB-C ↔ USB cable.
See the '''Serial connection''' section in the Ettus manual: [https://files.ettus.com/manual/page_usrp_x4xx.html]
# Change the static IP to a DHCP-assigned IP.
See the '''Network interfaces''' section: [https://files.ettus.com/manual/page_usrp_x4xx.html]

=== Updating the Filesystem ===
For full details, refer to the Ettus manual section: [https://files.ettus.com/manual/page_usrp_x4xx.html Updating Filesystems].

The easiest method is to perform the update directly on the X410 using the built-in <code>usrp_update_fs</code> utility:

<syntaxhighlight lang="bash">
# Login to the USRP
ssh root@usrp_ip

# Update filesystem to UHD 4.9
usrp_update_fs -t UHD-4.9

# Or install the UHD master version
usrp_update_fs -t master

# Reboot the USRP
reboot

# If the reboot works and the device is functional, commit the changes
mender commit
</syntaxhighlight>

=== Updating the FPGA Image ===
For details, see: [https://files.ettus.com/manual/page_usrp_x4xx.html Updating the FPGA].

You can verify and benchmark the X410 performance using the UHD example utility:

<syntaxhighlight lang="bash">
./benchmark_rate --args="mgmt_addr=10.89.12.177,addr=192.168.10.2,\
second_addr=192.168.11.2,clock_source=internal,time_source=internal" \
--rx_rate 200e6 --channels 0 --rx_channels 0
</syntaxhighlight>

== Installing Spectrum Sensing Example on x86 Architecture ==

This section provides a detailed procedure for installing and running the Spectrum Sensing example on an x86 architecture.
The '''spectrum_sensing''' folder within the NI-RF Data Recording API repository provides a ready-to-run demonstration of live RF spectrum sensing using a single receiver (e.g., USRP B206/X410) connected to an x86 host.

=== Setup Instructions ===
# '''Clone the repository:'''
<syntaxhighlight lang="bash">
git clone https://github.com/ni/ni-rf-data-recording-api.git
</syntaxhighlight>

# '''Clone the YOLOv5 repository:'''
<syntaxhighlight lang="bash">
git clone https://github.com/ultralytics/yolov5
</syntaxhighlight>

# '''Install dependencies for NI RF Data Recording API:'''
<syntaxhighlight lang="bash">
cd ni-rf-data-recording-api
pip install -r requirements.txt
</syntaxhighlight>

=== Python Package Dependencies ===
The following Python packages are required to run the spectrum sensing pipeline using the NI-RF Data Recording API.

* '''termcolor''' – Prints colored text in terminal for log readability.
* '''numpy (>=1.23.5, <2.0.0)''' – Core numerical library for IQ array operations, FFTs, and signal processing.
* '''scipy (>=1.4.1)''' – Used for filtering, spectral analysis, and mathematical routines.
* '''matplotlib (>=3.3)''' – Generates spectrum plots, spectrograms, and PSD visualizations.
* '''pandas (>=1.1.4)''' – Handles RF metadata and experiment logs.
* '''pyyaml (>=5.3.1)''' – Loads YAML configuration files for USRP setup parameters.
* '''nptdms''' – Enables reading and writing NI TDMS waveform files.
* '''sigmf''' – Implements Signal Metadata Format for storing IQ recordings with metadata.

# '''Install dependencies for the example:'''
<syntaxhighlight lang="bash">
cd ni-rf-data-recording-api/examples/spectrum_sensing
pip install -r requirements.txt
</syntaxhighlight>

=== Advanced Python Dependencies for Spectrum Sensing and ML Integration ===
These additional libraries enable advanced visualization, AI/ML inference, and web dashboard integration.

* '''dash''' – Web-based dashboard framework for real-time spectrum visualization.
* '''dash-daq''' – Adds instrumentation UI components for live control.
* '''dash-bootstrap-components''' – Provides responsive Bootstrap layouts for Dash apps.
* '''pillow (>=10.3.0)''' – Handles image saving and processing of spectrograms.
* '''torch (>=1.8.0)''' – PyTorch deep learning framework for inference/training.
* '''torchvision (>=0.9.0)''' – Vision utilities for preprocessing spectrograms.
* '''ultralytics (>=8.2.34)''' – YOLOv8 utilities for signal classification.
* '''gitpython (>=3.1.30)''' – Enables automated Git repository handling.
* '''opencv-python (>=4.1.1)''' – Performs spectrogram image manipulation.
* '''seaborn (>=0.11.0)''' – Provides data visualization and heatmaps.
* '''tqdm (>=4.66.3)''' – Adds progress bars during capture or inference.
* '''requests (>=2.32.2)''' – Handles model downloads and HTTP requests.
* '''setuptools (>=70.0.0, <80.9.0)''' – Ensures consistent Python packaging.

=== Configuring the Example ===
The configuration files are located at:
<code>~/ni-rf-data-recording-api/examples/spectrum_sensing/config/</code>

They define:
* RF parameters: center frequency, gain, bandwidth, sample rate
* Device type (e.g., B206) and connection interface
* Capture duration and number of records
* Output directory and naming conventions

=== Key Configuration Parameters ===
{| class="wikitable"
! Parameter !! Description !! Example
|-
| <code>"rx_recorded_data_path"</code> || Path to store captured IQ data || <code>"datasets/records/"</code>
|-
| <code>"nrecords"</code> || Number of snapshots to capture || <code>10</code>
|-
| <code>"freq"</code> || Center frequency (Hz) || <code>3.6e9</code>
|-
| <code>"rate"</code> || IQ sample rate (Sps) || <code>50e6</code>
|-
| <code>"bandwidth"</code> || Analog bandwidth || <code>20e6</code>
|-
| <code>"gain"</code> || RX gain (dB) || <code>40</code>
|-
| <code>"duration"</code> || Recording duration (s) || <code>0.04</code>
|-
| <code>"rate_source"</code> || Sample rate mode || <code>"user_defined"</code>
|-
| <code>"captured_data_file_name"</code> || Prefix for SigMF files || <code>"rx-waveform-td-rec-"</code>
|-
| <code>"antenna"</code> || Antenna port || <code>"TX/RX"</code>
|-
| <code>"clock_reference"</code> || Reference clock || <code>"internal"</code>
|}

=== Execution ===
(a) Run the UI application:
<syntaxhighlight lang="bash">
cd ~/ni-rf-data-recording-api/examples/spectrum_sensing
python spectrum_sensing.py
</syntaxhighlight>

After launching, you’ll see:
<code>Dash is running on http://127.0.0.1:8050/</code>
Open this link in your browser to access the dashboard.

* Load a configuration file from the dashboard.
* Click '''Start''' to begin sensing.
* IQ samples will be captured and saved in SigMF format at:
<code>~/ni-rf-data-recording-api/examples/spectrum_sensing/datasets/records</code>

[[File:Dashboard.png|thumb|800px|center|AI-based spectrum sensing dashboard using NI USRP SDRs and NI RF Data Recording API]]

'''Figure:''' AI-based spectrum sensing system using NI USRP SDRs, the NI RF Data Recording API, and a web-based control dashboard.

=== System Workflow Description ===
The figure above shows the end-to-end architecture for AI-driven spectrum sensing with NI USRPs.

* '''TX Configuration:''' User selects the waveform to transmit; it can be sent over-the-air or via RF cable.
* '''Start/Stop Control:''' Clicking '''Start''' launches the sensing and recording pipeline with live indicators for SDR initialization and capture status.

(b) Run the inference script:
<syntaxhighlight lang="bash">
cd ~/ni-rf-data-recording-api/examples/spectrum_sensing
python inference.py
</syntaxhighlight>

The inference script processes IQ recordings stored in:
<code>~/ni-rf-data-recording-api/examples/spectrum_sensing/datasets/records</code>

It converts each dataset into a spectrogram image saved at:
<code>~/ni-rf-data-recording-api/examples/spectrum_sensing/datasets/images</code>

The spectrograms are passed to a pre-trained '''YOLOv5''' model for signal classification.

[[File:inference_running.png|thumb|800px|center|YOLOv5-based live inference detecting a 5G NR signal with 96% confidence]]

'''Figure:''' Real-time inference output showing successful detection of a 5G NR waveform using a pre-trained YOLOv5 model.

=== Live Inference Visualization ===
After IQ samples are captured and stored, <code>inference.py</code> generates spectrograms and classifies signals.
In the shown example, the YOLOv5 model identifies a 5G NR waveform (<code>5GNR</code>) with a confidence score of '''0.96'''.
Detected signals show high classification accuracy and clear time-frequency boundaries.

== Spectrum Sensing Application with NI USRP and NVIDIA Jetson ==

This section summarizes the official documentation for running the <code>spectrum_sensing</code> application using NI USRP SDR hardware on NVIDIA Jetson platforms.

=== Overview ===
The application demonstrates real-time spectrum sensing by interfacing a NI USRP SDR (e.g., B206) with an NVIDIA Jetson device over USB 3.0. The Jetson hosts the NI RF Data Recording API and executes the entire data acquisition pipeline — including RF configuration, signal capture, visualization, and data formatting into SigMF files.
Because Jetson devices are ARM-based, a Jetson-specific PyTorch package is available from NVIDIA, while TorchVision must be built from source.

=== PyTorch Installation ===
# Install required dependencies:
<syntaxhighlight lang="bash">
sudo apt update
sudo apt install python3-pip libopenblas-base libopenmpi-dev
sudo pip3 install --upgrade pip
</syntaxhighlight>

# For Python 3.10 and JetPack 6.2.1, install PyTorch 2.5:
<syntaxhighlight lang="bash">
wget https://developer.download.nvidia.com/compute/redist/jp/v61/pytorch/torch-2.5.0a0+872d972e41.nv24.08.17622132-cp310-cp310-linux_aarch64.whl
pip3 install torch-2.5.0a0+872d972e41.nv24.08.17622132-cp310-cp310-linux_aarch64.whl
</syntaxhighlight>

# Fix libcusparse-related errors (if any):
<syntaxhighlight lang="bash">
mkdir -p ~/tmp_cusparselt && cd ~/tmp_cusparselt
wget https://developer.download.nvidia.com/compute/cusparselt/redist/libcusparse_lt/linux-aarch64/libcusparse_lt-linux-aarch64-0.7.0.0-archive.tar.xz

tar xf *.tar.xz
sudo cp -a libcusparse_lt-linux-aarch64-0.7.0.0-archive/include/* /usr/local/cuda/include/
sudo cp -a libcusparse_lt-linux-aarch64-0.7.0.0-archive/lib/* /usr/local/cuda/lib64/
sudo ldconfig
cd ~ && rm -rf ~/tmp_cusparselt

# Verify installation
python3 -c "import torch; print(torch.__version__); print(torch.cuda.is_available())"
# Output should show:
# 2.5.0a0+872 and True
</syntaxhighlight>

=== PyTorch Vision (torchvision) ===
# Install dependencies:
<syntaxhighlight lang="bash">
sudo apt-get install libjpeg-dev zlib1g-dev libpython3-dev libopenblas-dev \
libavcodec-dev libavformat-dev libswscale-dev
</syntaxhighlight>

# Clone the source repository:
<syntaxhighlight lang="bash">
git clone --branch v0.20.0 https://github.com/pytorch/vision.git
</syntaxhighlight>

# Build and install:
<syntaxhighlight lang="bash">
cd vision
export BUILD_VERSION=0.20.0
python3 setup.py build
python3 setup.py install
</syntaxhighlight>

=== Python Virtual Environment (Optional) ===
To isolate the working environment from the system:
# Install <code>venv</code> support:
<syntaxhighlight lang="bash">
sudo apt-get install python3.10-venv
</syntaxhighlight>

# Create and activate environment:
<syntaxhighlight lang="bash">
python3.10 -m venv .venv --system-site-packages --prompt demo
source .venv/bin/activate
</syntaxhighlight>

=== Python Requirements ===
# Install SigMF:
<syntaxhighlight lang="bash">
pip install sigmf
</syntaxhighlight>

# Install npTDMS:
<syntaxhighlight lang="bash">
pip install npTDMS
</syntaxhighlight>

# Colored terminal output:
<syntaxhighlight lang="bash">
pip install colored termcolor
</syntaxhighlight>

# Dash and dashboard components:
<syntaxhighlight lang="bash">
pip install dash dash_daq dash_bootstrap_components
</syntaxhighlight>

# YOLOv5 pre-requirements:
<syntaxhighlight lang="bash">
pip install -U "gitpython>=3.1.30" "matplotlib>=3.3" "numpy>=1.23.5" \
"opencv-python>=4.1.1" "pillow>=10.3.0" psutil "PyYAML>=5.3.1" \
"requests>=2.32.2" "scipy>=1.4.1" "thop>=0.1.1" "tqdm>=4.66.3" \
"ultralytics>=8.2.34" "setuptools>=70.0.0" "seaborn>=0.11.0"
</syntaxhighlight>

=== YOLOv5 Model ===
The demo application uses the YOLOv5 image detection model from Ultralytics (AGPL-3.0 license).

<syntaxhighlight lang="bash">
git clone https://github.com/ultralytics/yolov5
</syntaxhighlight>

=== Demo Code and Data Recording API ===
Clone the NI RF Data Recording API repository:
<syntaxhighlight lang="bash">
git clone https://github.com/ni/ni-rf-data-recording-api.git
</syntaxhighlight>

After all dependencies are installed, the Spectrum Sensing use case can be executed on Jetson following the same procedure as described for the x86 system.

== Waveform Creation and Signal Recording Pipeline ==

This section outlines the process for generating waveforms, capturing RF data using the NI-RF Data Recording API, and producing spectrogram images for machine learning applications.

=== Waveform Repository ===
The <code>src/waveforms/</code> directory contains all pre-generated test signals used with the NI RF Data Recording API.
It includes four subfolders: '''5G NR''', '''LTE''', '''Wi-Fi''', and '''Radar'''.

Each waveform consists of:
* '''IQ Data File''' (<code>.tdms</code> or <code>.mat</code>) — contains complex baseband samples.
* '''Configuration File''' (<code>.rfws</code>, <code>.yaml</code>, or <code>.csv</code>) — describes waveform parameters such as bandwidth and sampling rate.

'''Examples:'''
* LTE: <code>LTE_TDD_DL_20MHz_....tdms</code> + <code>...rfws</code>
* Radar: <code>Radar_Waveform_BW_2M.mat</code> + <code>Radar_Waveform_BW_2M.yaml</code>

[[File:waveform_repository.png|thumb|800px|center|Waveform repository flow]]

'''Figure:''' Waveform repository structure showing pre-generated 5G NR, LTE, Wi-Fi, and Radar signals mapped through the Wireless Link Parameter Dictionary.

=== Waveform Sources ===
* '''RFmx Waveform Creator:''' Used for generating 5G NR and LTE waveforms (<code>.tdms</code> + <code>.rfws</code>).
* '''IEEE MATLAB Wi-Fi Generator:''' Used for Wi-Fi test signals (<code>.mat</code> + <code>.csv</code>).
* '''Simulated Radar Generator (MATLAB):''' Used for radar signals (<code>.mat</code> + <code>.yaml</code>).

=== Usage in the API ===
During recording, JSON/YAML configuration files in <code>src/config/</code> reference these waveform paths.
The <code>wireless_link_parameter_map.yaml</code> dictionary maps waveform configuration fields (e.g., bandwidth, sampling rate, standard) to the SigMF metadata format — ensuring standardized dataset descriptions.

=== Recording IQ Data and Metadata via API ===
Once waveforms are prepared:

# Edit the configuration file (YAML/JSON) with your TX/RX parameters such as frequency, gain, and waveform paths.
# Run the recording:
<syntaxhighlight lang="bash">
python3 main_rf_data_recording_api.py --config path/to/your_config.yaml
</syntaxhighlight>
# The API maps parameters to SigMF metadata, controls USRP Tx/Rx via UHD, and writes:
** <code>.sigmf-data</code> (binary IQ samples)
** <code>.sigmf-meta</code> (JSON metadata)

=== Spectrogram Image Generation via Preprocessing ===
After dataset generation:

* Run preprocessing scripts (e.g., <code>rf_data_pre_processing_plot.py</code>) to visualize or convert SigMF recordings into time/frequency plots.
* Generate and crop spectrograms, partitioning them into training and validation sets for ML workflows.
* The structured image datasets form the foundation for AI-based spectrum classification and detection.

This end-to-end pipeline — from waveform generation to SigMF-formatted capture and spectrogram creation — enables reproducible, metadata-rich dataset production for AI-driven spectrum sensing research.

== How to use RF Data Recording API with user defined dataset? ==
To use the NI RF Data Recording API with a user-defined dataset for training and inference using YOLOv8, follow this multi-step process covering signal generation, data preprocessing, model training, and inference.

---

=== SigMF Data and Metadata Generation ===
Once the transmission signal is configured, stream IQ samples and record them in '''SigMF''' format by running <code>data_recording.py</code>:

* Location of the script:
: <code>/ni-rf-data-recording-api/examples/spectrum_sensing</code>

* SigMF outputs:
** <code>.sigmf-data</code>: Binary file with raw IQ samples.
** <code>.sigmf-meta</code>: JSON metadata (frequency, sample rate, gain, antenna, timestamps, etc.).

The script uses your YAML/JSON control file for parameters (center frequency, sample rate, bandwidth, gain, capture duration, number of records).

* Output directory:
: <code>/ni-rf-data-recording-api/examples/spectrum_sensing/datasets/records</code>

These SigMF files become the primary dataset for later analysis, visualization, and ML-based classification (e.g., spectrogram-based YOLO).

---

=== Spectrogram Generation and Dataset Preprocessing ===
Convert SigMF recordings into labeled spectrogram images using <code>pre-processing.py</code>. It orchestrates:

# <code>spectrogram_creator.py</code> – Reads <code>.sigmf-data</code>, applies STFT, saves spectrogram images (e.g., in <code>datasets/images</code>).
# <code>image_cropper.py</code> – Removes non-signal plot artifacts (axes, labels, borders) to produce clean images for detection models.
# <code>dataset_partitioner.py</code> – Splits dataset into train/val (e.g., 80/20) with balanced classes.
# <code>label_maker.py</code> – Creates YOLO-compatible label files for each image in the format:
: <code><class_id> <x_center> <y_center> <image_width> <image_height></code>

'''Resulting structure:'''
* Cleaned spectrogram images: <code>datasets/images</code>
* YOLO labels: <code>datasets/labels</code>
* Splits: <code>datasets/train</code>, <code>datasets/val</code>

This pipeline yields a model-ready dataset for accurate training and inference.

---

=== Dataset Configuration: <code>data.yaml</code> for YOLO Training ===
'''Fields:'''
* <code>train</code> – Path to training images
* <code>val</code> – Path to validation images
* <code>nc</code> – Number of classes
* <code>names</code> – List of class names in class-id order

'''Example:'''
<syntaxhighlight lang="yaml">
train: datasets/train/images
val: datasets/val/images

nc: 3
names: ['5gnr', 'wifi', 'lte']
</syntaxhighlight>

Use this file with YOLOv5/YOLOv8 training commands. Store it in the project root or inside the dataset folder.

---

=== Model Training Using YOLOv8 (Example) ===

==== Cloning YOLOv8 from Source ====
<syntaxhighlight lang="bash">
# Clone Ultralytics YOLOv8
git clone https://github.com/ultralytics/ultralytics.git
cd ultralytics

# (Optional) Virtual environment
python3 -m venv .venv
source .venv/bin/activate # Linux/macOS
# .venv\Scripts\activate # Windows PowerShell

# Install in editable mode
pip install --upgrade pip
pip install -e .
</syntaxhighlight>

Verify:
<syntaxhighlight lang="bash">
yolo help
</syntaxhighlight>

==== YOLOv8 Training Command ====
Train the nano model on your spectrogram dataset:
<syntaxhighlight lang="bash">
yolo detect train \
model=yolov8n.pt \
data=/content/dataset/data.yaml \
epochs=50 \
imgsz=640 \
batch=16 \
project=burst_train \
name=yolov8n_spectrogram
</syntaxhighlight>

'''Parameter notes:'''
* <code>model=yolov8n.pt</code> – Base architecture (nano).
* <code>data=...</code> – Path to <code>data.yaml</code>.
* <code>epochs=50</code> – Training epochs.
* <code>imgsz=640</code> – Input resolution.
* <code>batch=16</code> – Batch size.
* <code>project</code>/<code>name</code> – Output directories for logs/artifacts.

'''Outputs:'''
: <code>burst_train/yolov8n_spectrogram</code>
(Weights, logs, confusion matrices, PR curves, etc.)

== Conclusion ==
The NI RF Data Recording API provides a powerful and flexible framework for real-time spectrum sensing, dataset generation, and AI-driven signal classification across both x86 and embedded platforms such as NVIDIA Jetson.
By leveraging standardized formats like SigMF and integrating deep learning models such as YOLOv8, the framework enables a complete end-to-end workflow—from RF signal acquisition and metadata tagging to spectrogram creation, training, and live inference.

This modular approach allows researchers and engineers to rapidly prototype, evaluate, and deploy intelligent wireless sensing systems that bridge the gap between traditional SDR experimentation and modern AI-based spectrum analytics.
The same unified methodology can be extended to multi-band sensing, interference detection, cognitive radio, and 6G spectrum intelligence research, ensuring scalability and reproducibility in both laboratory and field environments.

[[Category:Application Notes]]

AI-Based Spectrum Sensing with Nvidia Jetson and USRP

2025-11-05T12:20:37Z

NeelPandeya: /* USRP B206 Overview */

== Application Note Number and Authors ==

'''AN-811'''

== Authors ==

Bharat Agarwal and Neel Pandeya

== Executive Summary ==

This application note presents a complete framework for real-time spectrum sensing using NI Universal Serial Radio Peripheral (USRP) Software-Defined Radios (SDRs) and NVIDIA Jetson or standard x86 compute platforms. The framework is not limited to a single USRP model—the X410, X310, and B2xx series (e.g., B206) can all be used as transmitters or receivers depending on the deployment scenario. The solution leverages the NI-RF Data Recording API to enable scalable RF data acquisition, SigMF-compliant metadata tagging, and seamless integration with machine learning workflows.

The document outlines three core usage scenarios:

# x86-Based Development Workflow: Using a workstation or server-class x86 machine, paired with high-end USRPs such as the X410 or X310, the system supports wideband spectrum sensing (up to 400 MHz instantaneous bandwidth per channel). This configuration is ideal for laboratory development, algorithm training, and high-throughput dataset generation.
# Jetson-Based Embedded Sensing (Primary Use Case): Using an NVIDIA Jetson platform as the host (e.g., AGX Orin) with a compact B206 SDR as receiver and an X410 as transmitter, the system delivers efficient edge inference with GPU acceleration. Although the B206 limits the instantaneous bandwidth to 56 MHz, this configuration emphasizes portability, low power, and real-time embedded operation.
# User-Defined Dataset Integration: In addition to live spectrum sensing, the framework supports integration and generation of user-defined datasets. This functionality extends the applicability of the system beyond real-time capture, enabling flexible experimentation, reproducibility, and seamless AI/ML dataset preparation. Two complementary capabilities are supported:
## SigMF Dataset Recording
##* All captured RF data is stored in the Signal Metadata Format (SigMF).
##* SigMF pairs raw IQ samples (<code>.sigmf-data</code>) with a corresponding metadata file (<code>.sigmf-meta</code>) in JSON format.
##* Metadata describes acquisition parameters such as frequency, bandwidth, gain, device type, timestamps, and scenario context.
##* Being human-readable and portable, SigMF datasets can be used across a wide range of software environments, making them ideal for wireless research, spectrum monitoring, AI/ML training for 6G, and regulatory validation.
##* Example: A spectrum sensing session at 3.5 GHz, 20 MHz bandwidth, and 10-second duration will result in a SigMF-compliant dataset ready for further processing or ML-based classification.
## Continuous Waveform Playback with User-Defined Files
##* The platform supports continuous transmission and replay of user-defined waveforms in TDMS or MATLAB (.mat) formats.
##* This allows testing with standard-compliant signals such as 5G NR, LTE, Radar, or Wi-Fi, or custom-designed waveforms.
##* By replaying predefined waveforms, researchers can benchmark algorithms, validate coexistence scenarios, and reproduce experiments consistently across testbeds.
##* Example: A MATLAB-generated LTE downlink frame can be continuously transmitted via an X410 while a B206 or X310 records the received signal in SigMF format for classification.

Together, these capabilities ensure that the NI-RF Data Recording API can handle both dataset creation (SigMF-based recording) and waveform-driven experimentation (TDMS/MAT playback), thereby covering the entire pipeline from signal generation to ML-ready dataset production.

By combining NI's reliable SDR hardware with NVIDIA's efficient edge compute platforms and a unified data interface, this solution supports a wide range of spectrum intelligence applications—from interference detection and dynamic spectrum access to embedded RF analytics. The methodology enables scalable deployment from lab to field, supporting real-time insights and long-term data collection in a streamlined, modular pipeline.

== USRP B206 Overview ==

[[File: USRP-b206_mini_01.jpg|thumb|center|400px|NI USRP B206 Software Defined Radio]]

The USRP B206 is a compact, low-cost SDR developed by NI / Ettus Research. It supports full-duplex operation with one transmit and one receive channel, making it ideal for a variety of wireless communication and sensing applications. The B206 covers a wide RF frequency range from 70 MHz to 6 GHz and supports up to 56 MHz of instantaneous bandwidth. This makes it suitable for applications such as spectrum sensing, dynamic spectrum access, and cognitive radio.

The device connects to a host system via a high-speed USB 3.0 interface, which enables data rates sufficient for wideband real-time signal acquisition and transmission. It also supports USB 2.0 with reduced performance. The B206 includes a Xilinx Spartan-6 FPGA for onboard signal processing and is powered either through USB or an external DC supply, the latter being preferred for optimal RF performance.

The USRP B206 is compatible with both x86 and ARM-based hosts, including embedded platforms like the NVIDIA Jetson series. This enables portable and energy-efficient deployment of spectrum sensing pipelines at the network edge. It is fully supported by the open-source UHD and integrates with popular SDR development tools such as GNU Radio, MATLAB, and LabVIEW.

Typical use cases for the B206 include real-time spectrum monitoring, wireless signal classification using machine learning, prototyping of 4G/5G systems, and SDR education and training. Its compact size and flexible software support make it an excellent choice for both laboratory research and embedded field deployments.

'''Key Features of the USRP B206:'''
* RF Capabilities: 1 TX, 1 RX, independently tunable, RF transceiver, 70 MHz to 6 GHz, up to 56 MHz bandwidth
* Programmable Logic: FPGA: Xilinx Spartan-6 XC6SLX150
* Software: UHD 4.9 or later, GNU Radio, C/C++ and Python
* Synchronization: REF (external 10 MHz or PPS reference)
* Digital Interfaces: USB 3.0, GPIO (8 I/O lines with 3.3 V I/O voltage), and JTAG
* Power, form factor: 5 V DC, 0.9 A maximum; Board-only: 84.3 mm × 51.0 mm × 8.7 mm; Enclosed: 84.9 mm × 55.7 mm × 19.8 mm

== NI-RF Data Recording API Overview ==

The '''[https://github.com/ni/ni-rf-data-recording-api/blob/main/README.md NI-RF Data Recording API]''' is an open-source, Python-based framework developed by National Instruments (NI) in collaboration with the Genesys Lab at Northeastern University. It is designed to streamline RF data collection using NI USRP SDRs, with support for structured metadata via the '''[https://github.com/sigmf/SigMF Signal Metadata Format (SigMF)]'''.

=== Purpose and Scope ===
This API enables efficient recording, labeling, and replay of real-world RF signals. It is particularly suited for generating datasets used in AI/ML workflows, wireless research, and spectrum monitoring. The framework abstracts low-level UHD interactions, allowing users to define RF parameters through JSON or YAML configuration files.

=== Key Features ===
* Support for both signal transmission and reception using NI USRP hardware.
* Native recording in SigMF format, capturing both IQ samples and rich metadata.
* Python-based, modular architecture supporting custom extensions and automation.
* Multi-SDR support via coordinated configuration files.
* Sample waveform libraries included (e.g., LTE, NR, radar, Wi-Fi) in TDMS/MAT formats.
* Utility scripts for standalone use: transmit, receive, replay, or continuous capture.

=== System Requirements ===
The API has been validated on Ubuntu 22.04 systems with the following dependencies:
* At least one compatible NI USRP device (e.g., B206, X310, X410).
* Installed UHD drivers with Python bindings.
* Python 3.x and required libraries (e.g., NumPy, PyYAML).
* Optional Docker environment for containerized deployment.

=== Relevance to Our Use Cases ===
In this application note, we explore three deployment scenarios of the NI-RF Data Recording API:

# x86-based Spectrum Sensing: Using the API on a desktop or server-class system, the USRP B206 is configured to perform spectrum capture, and the data is saved in SigMF format. This setup is optimal for high-throughput and lab-based development environments.
# Embedded Jetson Platform: The API is deployed on an NVIDIA Jetson device interfaced with the USRP B206 over USB 3.0. This enables compact, power-efficient, and real-time spectrum sensing at the edge. Onboard GPU resources are leveraged for FFT computation and ML inference.
# User-Defined Dataset Integration: The API provides flexible support for user-defined datasets through two complementary capabilities:
## Importing Pre-Generated Data: Users can seamlessly import and tag custom IQ recordings (e.g., SigMF-compliant files or previously captured spectrum data) into the repository. This enables integration of external datasets for benchmarking, anomaly detection, or reproducible research.
## Data Lake Storage for AI/ML Pipelines: All captured and imported datasets can be stored in a structured data lake, significantly simplifying automated dataset selection, management, and preprocessing. This facilitates streamlined workflows for AI/ML model design, training, and validation in spectrum sensing and 6G wireless research.

The NI-RF Data Recording API provides a flexible, hardware-agnostic foundation for both live RF capture and offline dataset handling, making it central to spectrum intelligence and edge-aware signal processing workflows.

== Reference Architecture for Spectrum Sensing ==

To support flexible and scalable RF data collection workflows, we propose a dual-mode reference architecture that demonstrates spectrum sensing using NI USRP hardware with two compute platforms: a high-performance x86 host and an embedded NVIDIA Jetson device. Both configurations utilize the NI-RF Data Recording API to capture, store, and manage RF data in SigMF format. The hardware setup supports real-time signal acquisition, tagging, and streaming for downstream machine learning or signal intelligence tasks.

=== x86-Based High-Performance Architecture ===

[[File: x86.png|thumb|center|900px|x86-based spectrum sensing architecture using NI USRP B206 and X410]]

In this high-performance lab-based deployment, a desktop-class x86 host system is used. The USRP X410 (or alternatively the X310) serves as the receiver, connected to the workstation via a 10 GbE Ethernet interface to support high-throughput data streaming. The transmitter is also an NI USRP X410, connected through a 10 GbE link via a network switch. A 30 dB attenuator is inserted between the TX and RX paths to protect the RF front-end from saturation during close-proximity transmission.

This configuration demonstrates the full high-performance capability of the platform, enabling wideband spectrum sensing and scalable data capture.

Host System Specifications:
* Operating System: Ubuntu 22.04
* UHD Compatibility: The NI-RF Data Recording API supports UHD ≥ 4.2. Most devices such as the X410 or X310 work with older versions, but the B206 requires UHD ≥ 4.9.
* Processor: Intel Xeon w7-2495X (24 cores, 2.5 GHz)

This setup is suited for '''high-throughput spectrum recording, algorithm development, and dataset generation''' in a lab environment. It offers large storage capacity, stable power, and CPU-intensive post-processing capabilities.

=== Jetson-Based Embedded Architecture ===

[[File:SS_with_x86.png|thumb|center|900px|Jetson-based spectrum sensing architecture using NI USRP B2x0 and X410]]

In this configuration, an NVIDIA Jetson module serves as the edge processing unit. The Jetson connects to a USRP B2x0 (e.g., B206) over a USB 3.0 interface, acting as the spectrum sensor (receiver). A USRP X410 acts as the transmitter, linked via a LAN switch. A 30 dB attenuator is used between the TX and RX paths to prevent RF front-end saturation during close-proximity transmission.

The Jetson executes the RF data acquisition pipeline and leverages onboard GPU resources to perform high-speed FFTs, signal classification, and real-time metadata tagging. A display, keyboard, and mouse connect directly for standalone operation.

'Jetson System Specifications:
* Operating System: Ubuntu 22.04 with JetPack 6.2.1
* UHD Version: 4.9
* Processor: NVIDIA Jetson AGX Orin 64 GB

This configuration is ideal for low-power, field-deployable sensing nodes where edge inference, minimal latency, and portability are required. The NI-RF Data Recording API runs natively on ARM-based Jetson, ensuring consistent data acquisition across architectures.

=== Common Features Across Architectures ===
Both architectures support:
* Real-time IQ sample recording and metadata tagging using NI-RF Data Recording API
* Integration with SigMF-compliant datasets
* Wideband RF capture across 70 MHz–6 GHz (with B206)
* Configurable gain, center frequency, bandwidth, and LO offsets via JSON/YAML files

The dual-platform design allows researchers to prototype, validate, and deploy spectrum sensing pipelines in a variety of scenarios—from power-constrained edge sensing to scalable, cloud-connected research environments.

== Bill of Materials ==

This section lists the hardware and software components required to replicate the spectrum sensing setup described in the reference architectures.

=== Jetson-Based Embedded Spectrum Sensing Setup ===
* '''NI USRP B206 SDR (Receiver)'''
** Frequency Range: 70 MHz – 6 GHz
** Bandwidth: up to 56 MHz
** Interface: USB 3.0

* '''NI USRP X410 SDR (Transmitter)'''
** Frequency Range: up to 7.2 GHz
** Bandwidth: up to 1 GHz per channel
** Interface: 10 GbE (SFP+)

* '''NVIDIA Jetson AGX Orin 64 GB Developer Kit (Edge Host)'''
** GPU: 2048-core Ampere GPU
** Interfaces: USB 3.0, 10 Gb Ethernet
** OS: Ubuntu 22.04 (ARM64) with JetPack 6.2.1

* '''Display and Input Devices'''
** Monitor (DisplayPort or HDMI)
** USB Keyboard and Mouse

* '''30 dB RF Attenuator'''
** Protects RX frontend during loopback or close-range transmission

* '''Network Switch (Gigabit)'''
** Routes LAN traffic between Jetson and X410

* '''RF Cables and Antennas or Dummy Load'''
* '''Power Supply for USRP X410 and Jetson'''
* '''USB 3.0 Cable (for Jetson–B206 interface)'''

=== x86-Based Spectrum Sensing Setup ===
* '''NI USRP B206 SDR (Receiver)'''
* '''NI USRP X410 SDR (Transmitter)'''
* '''x86 Workstation or Server (Host PC)'''
** CPU: Intel Xeon w7-2495X, 24 cores, 2.5 GHz
** OS: Ubuntu 22.04 LTS
** UHD: Version 4.8 or newer
** RAM: Minimum 32 GB recommended
** Storage: SSD for high-speed IQ data logging

* '''Display and Input Devices'''
** Monitor (DisplayPort or HDMI)
** USB Keyboard and Mouse

* '''30 dB RF Attenuator'''
* '''USB 3.0 Cable (PC–B206 interface)'''
* '''Ethernet Cables (PC and X410 to switch)'''
* '''Network Switch (Gigabit or 10 GbE)'''
* '''Coaxial Cable (RF connection between TX and RX)'''

=== Software Requirements (Common) ===
* '''NI-RF Data Recording API'''
** GitHub: [https://github.com/ni/ni-rf-data-recording-api https://github.com/ni/ni-rf-data-recording-api]
** Supports SigMF format, YAML/JSON configuration, UHD interface

* '''UHD (USRP Hardware Driver)'''
** Version 4.9 recommended
** Installed natively

* '''Python 3.x Environment'''
** Required packages: numpy, pyyaml, sigmf, uhd, etc.

== Hardware Requirements ==

To implement the proposed spectrum sensing architecture, the following hardware components are required. The selected devices are chosen for their compatibility with the NI-RF Data Recording API, support for UHD drivers, and ability to perform high-speed RF acquisition and processing.

=== NI USRP B206 (Receiver SDR) ===
The USRP B206 is a low-cost, full-duplex software-defined radio with wide RF coverage and USB 3.0 connectivity, making it ideal for spectrum sensing tasks.

* '''Frequency Range:''' 70 MHz – 6 GHz
* '''Bandwidth:''' Up to 56 MHz
* '''Interface:''' USB 3.0
* '''Form Factor:''' Compact, bus-powered or DC-powered
* '''Purchase Link:''' [https://www.ettus.com/all-products/usrp-b200/ https://www.ettus.com/all-products/usrp-b200/]

=== NI USRP X410 (Transmitter SDR) ===
The USRP X410 is a high-performance, 4-channel SDR capable of wideband signal transmission and reception. It supports 10 GbE connectivity and real-time FPGA processing.

* '''Frequency Range:''' Up to 7.2 GHz
* '''Bandwidth:''' Up to 1 GHz per channel
* '''Interface:''' 10 GbE (SFP+), PCIe (optional)
* '''FPGA:''' Xilinx Zynq Ultrascale+ RFSoC
* '''Purchase Link:''' [https://www.ettus.com/all-products/usrp-x410/ https://www.ettus.com/all-products/usrp-x410/]

=== NVIDIA Jetson AGX Orin 64 GB Developer Kit (Edge Host) ===
The Jetson AGX Orin series provides a powerful embedded GPU platform for edge AI and RF signal processing.

* '''GPU:''' NVIDIA Ampere architecture
* '''RAM:''' 32 GB / 64 GB LPDDR4/5
* '''Connectivity:''' USB 3.0, Ethernet, GPIO
* '''OS Support:''' Ubuntu 20.04 / 22.04 (ARM64)
* '''Purchase Link:''' [https://store.nvidia.com/jetson/store/ https://store.nvidia.com/jetson/store/]

=== Network Switch (Gigabit or 10 GbE) ===
A managed or unmanaged Ethernet switch is required to route LAN traffic between the Jetson or x86 host and the USRP X410.

* '''Recommended:''' Netgear GS108, Mikrotik CRS305, or Cisco CBS350
* '''Typical Ports:''' 8+ (Gigabit or 10 GbE SFP+)
* '''Example Link:''' [https://www.netgear.com/business/wired/switches/smart/gs108/ https://www.netgear.com/business/wired/switches/smart/gs108/]

=== High-Performance x86 Host (Optional for Lab Use) ===
An x86 workstation is recommended for development, high-throughput data collection, or as an alternative to Jetson in a lab environment.

* '''Processor:''' Minimum specification of an 8-core CPU at 3 GHz or higher (e.g., Intel Xeon or equivalent). Higher core counts (e.g., 24-core Xeon W7-2495X) can improve throughput and parallel data processing but are not mandatory.
* '''RAM:''' 64 GB or more
* '''Storage:''' NVMe SSD for high-speed data logging
* '''Operating System:''' Ubuntu 22.04 LTS
* '''Form Factor:''' Tower workstation or server

=== RF Accessories ===
* '''RF Coaxial Cables (SMA)'''
* '''30 dB Attenuator''' – Protects RX during close TX–RX loopback tests
* '''Antennas''' (Wideband or band-specific)
* '''Dummy Load''' (for isolated lab TX tests)
* '''USB 3.0 Cable''' (for USRP B206)
* '''Ethernet Cables''' (Cat 6 or SFP+ DAC for X410)
* '''Power Supplies:'''
** Jetson: 19 V / 4.74 A adapter (usually included)
** X410: External DC or rack supply per specifications

== Software Requirements ==

This section outlines the required software components for enabling spectrum sensing using the NI-RF Data Recording API with USRP B206/X410 and NVIDIA Jetson or x86 hosts. These tools are compatible across both embedded and desktop-class platforms and support real-time signal acquisition and metadata tagging in SigMF format.

=== Ubuntu Operating System ===
* '''Version:''' Ubuntu 22.04 LTS (Jetson) / Ubuntu 22.04 LTS (x86 recommended)
* '''Download Link:''' [https://ubuntu.com/download https://ubuntu.com/download]
* '''Jetson OS Image:''' JetPack SDK includes Ubuntu and NVIDIA drivers
* '''JetPack Link:''' [https://developer.nvidia.com/embedded/jetpack https://developer.nvidia.com/embedded/jetpack]

=== NI-RF Data Recording API ===
* '''Description:''' Open-source Python API developed by NI and the Genesys Lab (Northeastern University) for recording and labeling RF data in SigMF format using USRP devices.
* '''Features:''' Configurable YAML/JSON setups, multi-SDR coordination, SigMF conversion, supports transmission/reception workflows.
* '''Repository:''' [https://github.com/ni/ni-rf-data-recording-api https://github.com/ni/ni-rf-data-recording-api]

=== UHD – USRP Hardware Driver ===
* '''Description:''' The official driver and API library for controlling and interfacing with all NI/Ettus USRP SDR hardware. Required for low-level communication between Python and the hardware.
* '''Version:''' The NI-RF Data Recording API requires a UHD version that supports the selected USRP device:
** For X410 (and other X-Series): UHD ≥ 4.2 (first stable release UHD 4.4 recommended)
** For B206: UHD ≥ 4.9 required
* '''Repository:''' [https://github.com/EttusResearch/uhd https://github.com/EttusResearch/uhd]
* '''Install Guide:''' [https://kb.ettus.com/Building_and_Installing_the_USRP_Open-Source_Toolchain_(UHD_and_GNU_Radio)_on_Linux UHD and GNU Radio Install Guide]

=== Python Environment ===
* '''Version:''' Python 3.10.12 or newer
* '''Required Packages:'''
** <code>numpy</code>, <code>pyyaml</code>, <code>sigmf</code>, <code>uhd</code>, <code>scipy</code>, <code>matplotlib</code>, etc.
* '''Package Manager:''' <code>pip</code> or <code>conda</code>
* '''Recommended Setup:''' Create a Python virtual environment for isolation and reproducibility.
* '''Download Link:''' [https://www.python.org/ https://www.python.org/]

=== SigMF Library (Python) ===
* '''Description:''' Used for generating and parsing metadata in the Signal Metadata Format (SigMF), enabling dataset interoperability and ML dataset labeling.
* '''Supported Version:''' Validated with '''SigMF 1.0.0''' (later versions such as 1.1.x or 1.2.x introduce major changes and have not been validated).
* '''Repository:''' [https://github.com/gnuradio/sigmf-numpy https://github.com/gnuradio/sigmf-numpy]
* '''Installation Command:''' <code>pip install sigmf==1.0.0</code>
* '''Reference:''' For more details, see the [https://github.com/ni/ni-rf-data-recording-api/tree/main/docs NI RF Data Recording API Getting Started Guide].

== Installing and Configuring the UHD Software ==

This section explains how to build and install the USRP Hardware Driver (UHD) from source code. At the time of this writing, the recommended version is '''UHD 4.9'''.

* It is strongly recommended to build UHD from source rather than installing from binary packages to ensure compatibility and access to the latest updates.
* For x86/64 Ubuntu systems with released UHD versions available, you may install via APT Debian packages.
* For Jetson (ARM64) systems, UHD must be built from source since no binary packages are provided.

---

Before building UHD, install all required dependencies (Ubuntu 22.04):

'''Note:''' If your system already has another UHD version installed, remove it first:

<syntaxhighlight lang="bash">
sudo apt remove libuhd* uhd-host
sudo rm -rf /usr/lib/uhd /usr/include/uhd /usr/local/lib/uhd /usr/local/include/uhd
</syntaxhighlight>

Then install build dependencies:

<syntaxhighlight lang="bash">
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
</syntaxhighlight>

Clone the UHD repository and check out version '''v4.9.0.0''':

<syntaxhighlight lang="bash">
git clone https://github.com/EttusResearch/uhd.git
cd uhd
git checkout v4.9.0.0
</syntaxhighlight>

Build and install UHD:

<syntaxhighlight lang="bash">
cd host
mkdir build && cd build
cmake ..
make -j$(nproc)
sudo make install
sudo ldconfig
export LD_LIBRARY_PATH=/usr/local/lib
sudo usrp_images_downloader
</syntaxhighlight>

Verify the installation:

<syntaxhighlight lang="bash">
uhd_usrp_probe
uhd_find_devices
</syntaxhighlight>

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

[[File:fae8d810-08f0-4ae3-ab87-5b6a31eeaa66.png|thumb|400px|center|uhd_usrp_probe output for B206]]
[[File:5026560b-fc07-4f77-953c-c17f41acfccc.png|thumb|400px|center|uhd_find_devices output for N310 and X410]]

'''Figure:''' Examples of UHD utilities used for USRP probing and device discovery.

=== Post UHD Installation Tasks ===
# '''Download USRP images'''
<syntaxhighlight lang="bash">
sudo /usr/local/bin/uhd_images_downloader
</syntaxhighlight>

# '''Add USB udev rule''' (can be limited to specific vendor/device IDs)
<syntaxhighlight lang="bash">
sudo nano /etc/udev/rules.d/99-usb.rules
# Add this line:
# SUBSYSTEM=="usb",MODE="0666"
sudo udevadm control --reload-rules
sudo udevadm trigger
</syntaxhighlight>

# Unplug and replug the USB device if it was already connected.

# '''Enable Python UHD API visibility'''
<syntaxhighlight lang="bash">
echo "/usr/local/lib/python3.10/site-packages" | \
sudo tee /usr/local/lib/python3.10/dist-packages/local-site-packages.pth
</syntaxhighlight>

=== UHD Installation Verification ===
# '''Find connected USRP devices'''
<syntaxhighlight lang="bash">
uhd_find_devices
</syntaxhighlight>

# '''Run throughput benchmark on the B2x0 device'''
<syntaxhighlight lang="bash">
/usr/local/lib/uhd/examples/benchmark_rate --args "type=b200" --rx_rate 10e6
</syntaxhighlight>

# '''Run Python throughput benchmark'''
<syntaxhighlight lang="bash">
python3.10 /usr/local/lib/uhd/examples/python/benchmark_rate.py --args "type=b200" --rx_rate 10e6
</syntaxhighlight>

== Installing and Configuring the USRP X410 Radio ==

For detailed documentation, see the official Ettus manual:
[https://files.ettus.com/manual/page_usrp_x4xx.html https://files.ettus.com/manual/page_usrp_x4xx.html]

=== Connecting to the X410 ===
You can connect to the USRP X410 using either of the following interfaces:
* Ethernet (RJ45)
* USB-C JTAG Console

If you cannot connect to the X410 (e.g., because it has a static IP address):

# Connect the USRP to your PC using a USB-C ↔ USB cable.
See the '''Serial connection''' section in the Ettus manual: [https://files.ettus.com/manual/page_usrp_x4xx.html]
# Change the static IP to a DHCP-assigned IP.
See the '''Network interfaces''' section: [https://files.ettus.com/manual/page_usrp_x4xx.html]

=== Updating the Filesystem ===
For full details, refer to the Ettus manual section: [https://files.ettus.com/manual/page_usrp_x4xx.html Updating Filesystems].

The easiest method is to perform the update directly on the X410 using the built-in <code>usrp_update_fs</code> utility:

<syntaxhighlight lang="bash">
# Login to the USRP
ssh root@usrp_ip

# Update filesystem to UHD 4.9
usrp_update_fs -t UHD-4.9

# Or install the UHD master version
usrp_update_fs -t master

# Reboot the USRP
reboot

# If the reboot works and the device is functional, commit the changes
mender commit
</syntaxhighlight>

=== Updating the FPGA Image ===
For details, see: [https://files.ettus.com/manual/page_usrp_x4xx.html Updating the FPGA].

You can verify and benchmark the X410 performance using the UHD example utility:

<syntaxhighlight lang="bash">
./benchmark_rate --args="mgmt_addr=10.89.12.177,addr=192.168.10.2,\
second_addr=192.168.11.2,clock_source=internal,time_source=internal" \
--rx_rate 200e6 --channels 0 --rx_channels 0
</syntaxhighlight>

== Installing Spectrum Sensing Example on x86 Architecture ==

This section provides a detailed procedure for installing and running the Spectrum Sensing example on an x86 architecture.
The '''spectrum_sensing''' folder within the NI-RF Data Recording API repository provides a ready-to-run demonstration of live RF spectrum sensing using a single receiver (e.g., USRP B206/X410) connected to an x86 host.

=== Setup Instructions ===
# '''Clone the repository:'''
<syntaxhighlight lang="bash">
git clone https://github.com/ni/ni-rf-data-recording-api.git
</syntaxhighlight>

# '''Clone the YOLOv5 repository:'''
<syntaxhighlight lang="bash">
git clone https://github.com/ultralytics/yolov5
</syntaxhighlight>

# '''Install dependencies for NI RF Data Recording API:'''
<syntaxhighlight lang="bash">
cd ni-rf-data-recording-api
pip install -r requirements.txt
</syntaxhighlight>

=== Python Package Dependencies ===
The following Python packages are required to run the spectrum sensing pipeline using the NI-RF Data Recording API.

* '''termcolor''' – Prints colored text in terminal for log readability.
* '''numpy (>=1.23.5, <2.0.0)''' – Core numerical library for IQ array operations, FFTs, and signal processing.
* '''scipy (>=1.4.1)''' – Used for filtering, spectral analysis, and mathematical routines.
* '''matplotlib (>=3.3)''' – Generates spectrum plots, spectrograms, and PSD visualizations.
* '''pandas (>=1.1.4)''' – Handles RF metadata and experiment logs.
* '''pyyaml (>=5.3.1)''' – Loads YAML configuration files for USRP setup parameters.
* '''nptdms''' – Enables reading and writing NI TDMS waveform files.
* '''sigmf''' – Implements Signal Metadata Format for storing IQ recordings with metadata.

# '''Install dependencies for the example:'''
<syntaxhighlight lang="bash">
cd ni-rf-data-recording-api/examples/spectrum_sensing
pip install -r requirements.txt
</syntaxhighlight>

=== Advanced Python Dependencies for Spectrum Sensing and ML Integration ===
These additional libraries enable advanced visualization, AI/ML inference, and web dashboard integration.

* '''dash''' – Web-based dashboard framework for real-time spectrum visualization.
* '''dash-daq''' – Adds instrumentation UI components for live control.
* '''dash-bootstrap-components''' – Provides responsive Bootstrap layouts for Dash apps.
* '''pillow (>=10.3.0)''' – Handles image saving and processing of spectrograms.
* '''torch (>=1.8.0)''' – PyTorch deep learning framework for inference/training.
* '''torchvision (>=0.9.0)''' – Vision utilities for preprocessing spectrograms.
* '''ultralytics (>=8.2.34)''' – YOLOv8 utilities for signal classification.
* '''gitpython (>=3.1.30)''' – Enables automated Git repository handling.
* '''opencv-python (>=4.1.1)''' – Performs spectrogram image manipulation.
* '''seaborn (>=0.11.0)''' – Provides data visualization and heatmaps.
* '''tqdm (>=4.66.3)''' – Adds progress bars during capture or inference.
* '''requests (>=2.32.2)''' – Handles model downloads and HTTP requests.
* '''setuptools (>=70.0.0, <80.9.0)''' – Ensures consistent Python packaging.

=== Configuring the Example ===
The configuration files are located at:
<code>~/ni-rf-data-recording-api/examples/spectrum_sensing/config/</code>

They define:
* RF parameters: center frequency, gain, bandwidth, sample rate
* Device type (e.g., B206) and connection interface
* Capture duration and number of records
* Output directory and naming conventions

=== Key Configuration Parameters ===
{| class="wikitable"
! Parameter !! Description !! Example
|-
| <code>"rx_recorded_data_path"</code> || Path to store captured IQ data || <code>"datasets/records/"</code>
|-
| <code>"nrecords"</code> || Number of snapshots to capture || <code>10</code>
|-
| <code>"freq"</code> || Center frequency (Hz) || <code>3.6e9</code>
|-
| <code>"rate"</code> || IQ sample rate (Sps) || <code>50e6</code>
|-
| <code>"bandwidth"</code> || Analog bandwidth || <code>20e6</code>
|-
| <code>"gain"</code> || RX gain (dB) || <code>40</code>
|-
| <code>"duration"</code> || Recording duration (s) || <code>0.04</code>
|-
| <code>"rate_source"</code> || Sample rate mode || <code>"user_defined"</code>
|-
| <code>"captured_data_file_name"</code> || Prefix for SigMF files || <code>"rx-waveform-td-rec-"</code>
|-
| <code>"antenna"</code> || Antenna port || <code>"TX/RX"</code>
|-
| <code>"clock_reference"</code> || Reference clock || <code>"internal"</code>
|}

=== Execution ===
(a) Run the UI application:
<syntaxhighlight lang="bash">
cd ~/ni-rf-data-recording-api/examples/spectrum_sensing
python spectrum_sensing.py
</syntaxhighlight>

After launching, you’ll see:
<code>Dash is running on http://127.0.0.1:8050/</code>
Open this link in your browser to access the dashboard.

* Load a configuration file from the dashboard.
* Click '''Start''' to begin sensing.
* IQ samples will be captured and saved in SigMF format at:
<code>~/ni-rf-data-recording-api/examples/spectrum_sensing/datasets/records</code>

[[File:Dashboard.png|thumb|800px|center|AI-based spectrum sensing dashboard using NI USRP SDRs and NI RF Data Recording API]]

'''Figure:''' AI-based spectrum sensing system using NI USRP SDRs, the NI RF Data Recording API, and a web-based control dashboard.

=== System Workflow Description ===
The figure above shows the end-to-end architecture for AI-driven spectrum sensing with NI USRPs.

* '''TX Configuration:''' User selects the waveform to transmit; it can be sent over-the-air or via RF cable.
* '''Start/Stop Control:''' Clicking '''Start''' launches the sensing and recording pipeline with live indicators for SDR initialization and capture status.

(b) Run the inference script:
<syntaxhighlight lang="bash">
cd ~/ni-rf-data-recording-api/examples/spectrum_sensing
python inference.py
</syntaxhighlight>

The inference script processes IQ recordings stored in:
<code>~/ni-rf-data-recording-api/examples/spectrum_sensing/datasets/records</code>

It converts each dataset into a spectrogram image saved at:
<code>~/ni-rf-data-recording-api/examples/spectrum_sensing/datasets/images</code>

The spectrograms are passed to a pre-trained '''YOLOv5''' model for signal classification.

[[File:inference_running.png|thumb|800px|center|YOLOv5-based live inference detecting a 5G NR signal with 96% confidence]]

'''Figure:''' Real-time inference output showing successful detection of a 5G NR waveform using a pre-trained YOLOv5 model.

=== Live Inference Visualization ===
After IQ samples are captured and stored, <code>inference.py</code> generates spectrograms and classifies signals.
In the shown example, the YOLOv5 model identifies a 5G NR waveform (<code>5GNR</code>) with a confidence score of '''0.96'''.
Detected signals show high classification accuracy and clear time-frequency boundaries.

== Spectrum Sensing Application with NI USRP and NVIDIA Jetson ==

This section summarizes the official documentation for running the <code>spectrum_sensing</code> application using NI USRP SDR hardware on NVIDIA Jetson platforms.

=== Overview ===
The application demonstrates real-time spectrum sensing by interfacing a NI USRP SDR (e.g., B206) with an NVIDIA Jetson device over USB 3.0. The Jetson hosts the NI RF Data Recording API and executes the entire data acquisition pipeline — including RF configuration, signal capture, visualization, and data formatting into SigMF files.
Because Jetson devices are ARM-based, a Jetson-specific PyTorch package is available from NVIDIA, while TorchVision must be built from source.

=== PyTorch Installation ===
# Install required dependencies:
<syntaxhighlight lang="bash">
sudo apt update
sudo apt install python3-pip libopenblas-base libopenmpi-dev
sudo pip3 install --upgrade pip
</syntaxhighlight>

# For Python 3.10 and JetPack 6.2.1, install PyTorch 2.5:
<syntaxhighlight lang="bash">
wget https://developer.download.nvidia.com/compute/redist/jp/v61/pytorch/torch-2.5.0a0+872d972e41.nv24.08.17622132-cp310-cp310-linux_aarch64.whl
pip3 install torch-2.5.0a0+872d972e41.nv24.08.17622132-cp310-cp310-linux_aarch64.whl
</syntaxhighlight>

# Fix libcusparse-related errors (if any):
<syntaxhighlight lang="bash">
mkdir -p ~/tmp_cusparselt && cd ~/tmp_cusparselt
wget https://developer.download.nvidia.com/compute/cusparselt/redist/libcusparse_lt/linux-aarch64/libcusparse_lt-linux-aarch64-0.7.0.0-archive.tar.xz

tar xf *.tar.xz
sudo cp -a libcusparse_lt-linux-aarch64-0.7.0.0-archive/include/* /usr/local/cuda/include/
sudo cp -a libcusparse_lt-linux-aarch64-0.7.0.0-archive/lib/* /usr/local/cuda/lib64/
sudo ldconfig
cd ~ && rm -rf ~/tmp_cusparselt

# Verify installation
python3 -c "import torch; print(torch.__version__); print(torch.cuda.is_available())"
# Output should show:
# 2.5.0a0+872 and True
</syntaxhighlight>

=== PyTorch Vision (torchvision) ===
# Install dependencies:
<syntaxhighlight lang="bash">
sudo apt-get install libjpeg-dev zlib1g-dev libpython3-dev libopenblas-dev \
libavcodec-dev libavformat-dev libswscale-dev
</syntaxhighlight>

# Clone the source repository:
<syntaxhighlight lang="bash">
git clone --branch v0.20.0 https://github.com/pytorch/vision.git
</syntaxhighlight>

# Build and install:
<syntaxhighlight lang="bash">
cd vision
export BUILD_VERSION=0.20.0
python3 setup.py build
python3 setup.py install
</syntaxhighlight>

=== Python Virtual Environment (Optional) ===
To isolate the working environment from the system:
# Install <code>venv</code> support:
<syntaxhighlight lang="bash">
sudo apt-get install python3.10-venv
</syntaxhighlight>

# Create and activate environment:
<syntaxhighlight lang="bash">
python3.10 -m venv .venv --system-site-packages --prompt demo
source .venv/bin/activate
</syntaxhighlight>

=== Python Requirements ===
# Install SigMF:
<syntaxhighlight lang="bash">
pip install sigmf
</syntaxhighlight>

# Install npTDMS:
<syntaxhighlight lang="bash">
pip install npTDMS
</syntaxhighlight>

# Colored terminal output:
<syntaxhighlight lang="bash">
pip install colored termcolor
</syntaxhighlight>

# Dash and dashboard components:
<syntaxhighlight lang="bash">
pip install dash dash_daq dash_bootstrap_components
</syntaxhighlight>

# YOLOv5 pre-requirements:
<syntaxhighlight lang="bash">
pip install -U "gitpython>=3.1.30" "matplotlib>=3.3" "numpy>=1.23.5" \
"opencv-python>=4.1.1" "pillow>=10.3.0" psutil "PyYAML>=5.3.1" \
"requests>=2.32.2" "scipy>=1.4.1" "thop>=0.1.1" "tqdm>=4.66.3" \
"ultralytics>=8.2.34" "setuptools>=70.0.0" "seaborn>=0.11.0"
</syntaxhighlight>

=== YOLOv5 Model ===
The demo application uses the YOLOv5 image detection model from Ultralytics (AGPL-3.0 license).

<syntaxhighlight lang="bash">
git clone https://github.com/ultralytics/yolov5
</syntaxhighlight>

=== Demo Code and Data Recording API ===
Clone the NI RF Data Recording API repository:
<syntaxhighlight lang="bash">
git clone https://github.com/ni/ni-rf-data-recording-api.git
</syntaxhighlight>

After all dependencies are installed, the Spectrum Sensing use case can be executed on Jetson following the same procedure as described for the x86 system.

== Waveform Creation and Signal Recording Pipeline ==

This section outlines the process for generating waveforms, capturing RF data using the NI-RF Data Recording API, and producing spectrogram images for machine learning applications.

=== Waveform Repository ===
The <code>src/waveforms/</code> directory contains all pre-generated test signals used with the NI RF Data Recording API.
It includes four subfolders: '''5G NR''', '''LTE''', '''Wi-Fi''', and '''Radar'''.

Each waveform consists of:
* '''IQ Data File''' (<code>.tdms</code> or <code>.mat</code>) — contains complex baseband samples.
* '''Configuration File''' (<code>.rfws</code>, <code>.yaml</code>, or <code>.csv</code>) — describes waveform parameters such as bandwidth and sampling rate.

'''Examples:'''
* LTE: <code>LTE_TDD_DL_20MHz_....tdms</code> + <code>...rfws</code>
* Radar: <code>Radar_Waveform_BW_2M.mat</code> + <code>Radar_Waveform_BW_2M.yaml</code>

[[File: waveform_repository.png|thumb|800px|center|Waveform repository flow]]

'''Figure:''' Waveform repository structure showing pre-generated 5G NR, LTE, Wi-Fi, and Radar signals mapped through the Wireless Link Parameter Dictionary.

=== Waveform Sources ===
* '''RFmx Waveform Creator:''' Used for generating 5G NR and LTE waveforms (<code>.tdms</code> + <code>.rfws</code>).
* '''IEEE MATLAB Wi-Fi Generator:''' Used for Wi-Fi test signals (<code>.mat</code> + <code>.csv</code>).
* '''Simulated Radar Generator (MATLAB):''' Used for radar signals (<code>.mat</code> + <code>.yaml</code>).

=== Usage in the API ===
During recording, JSON/YAML configuration files in <code>src/config/</code> reference these waveform paths.
The <code>wireless_link_parameter_map.yaml</code> dictionary maps waveform configuration fields (e.g., bandwidth, sampling rate, standard) to the SigMF metadata format — ensuring standardized dataset descriptions.

=== Recording IQ Data and Metadata via API ===
Once waveforms are prepared:

# Edit the configuration file (YAML/JSON) with your TX/RX parameters such as frequency, gain, and waveform paths.
# Run the recording:
<syntaxhighlight lang="bash">
python3 main_rf_data_recording_api.py --config path/to/your_config.yaml
</syntaxhighlight>
# The API maps parameters to SigMF metadata, controls USRP Tx/Rx via UHD, and writes:
** <code>.sigmf-data</code> (binary IQ samples)
** <code>.sigmf-meta</code> (JSON metadata)

=== Spectrogram Image Generation via Preprocessing ===
After dataset generation:

* Run preprocessing scripts (e.g., <code>rf_data_pre_processing_plot.py</code>) to visualize or convert SigMF recordings into time/frequency plots.
* Generate and crop spectrograms, partitioning them into training and validation sets for ML workflows.
* The structured image datasets form the foundation for AI-based spectrum classification and detection.

This end-to-end pipeline — from waveform generation to SigMF-formatted capture and spectrogram creation — enables reproducible, metadata-rich dataset production for AI-driven spectrum sensing research.

== How to use RF Data Recording API with user defined dataset? ==
To use the NI RF Data Recording API with a user-defined dataset for training and inference using YOLOv8, follow this multi-step process covering signal generation, data preprocessing, model training, and inference.

---

=== SigMF Data and Metadata Generation ===
Once the transmission signal is configured, stream IQ samples and record them in '''SigMF''' format by running <code>data_recording.py</code>:

* Location of the script:
: <code>/ni-rf-data-recording-api/examples/spectrum_sensing</code>

* SigMF outputs:
** <code>.sigmf-data</code>: Binary file with raw IQ samples.
** <code>.sigmf-meta</code>: JSON metadata (frequency, sample rate, gain, antenna, timestamps, etc.).

The script uses your YAML/JSON control file for parameters (center frequency, sample rate, bandwidth, gain, capture duration, number of records).

* Output directory:
: <code>/ni-rf-data-recording-api/examples/spectrum_sensing/datasets/records</code>

These SigMF files become the primary dataset for later analysis, visualization, and ML-based classification (e.g., spectrogram-based YOLO).

---

=== Spectrogram Generation and Dataset Preprocessing ===
Convert SigMF recordings into labeled spectrogram images using <code>pre-processing.py</code>. It orchestrates:

# <code>spectrogram_creator.py</code> – Reads <code>.sigmf-data</code>, applies STFT, saves spectrogram images (e.g., in <code>datasets/images</code>).
# <code>image_cropper.py</code> – Removes non-signal plot artifacts (axes, labels, borders) to produce clean images for detection models.
# <code>dataset_partitioner.py</code> – Splits dataset into train/val (e.g., 80/20) with balanced classes.
# <code>label_maker.py</code> – Creates YOLO-compatible label files for each image in the format:
: <code><class_id> <x_center> <y_center> <image_width> <image_height></code>

'''Resulting structure:'''
* Cleaned spectrogram images: <code>datasets/images</code>
* YOLO labels: <code>datasets/labels</code>
* Splits: <code>datasets/train</code>, <code>datasets/val</code>

This pipeline yields a model-ready dataset for accurate training and inference.

---

=== Dataset Configuration: <code>data.yaml</code> for YOLO Training ===
'''Fields:'''
* <code>train</code> – Path to training images
* <code>val</code> – Path to validation images
* <code>nc</code> – Number of classes
* <code>names</code> – List of class names in class-id order

'''Example:'''
<syntaxhighlight lang="yaml">
train: datasets/train/images
val: datasets/val/images

nc: 3
names: ['5gnr', 'wifi', 'lte']
</syntaxhighlight>

Use this file with YOLOv5/YOLOv8 training commands. Store it in the project root or inside the dataset folder.

---

=== Model Training Using YOLOv8 (Example) ===

==== Cloning YOLOv8 from Source ====
<syntaxhighlight lang="bash">
# Clone Ultralytics YOLOv8
git clone https://github.com/ultralytics/ultralytics.git
cd ultralytics

# (Optional) Virtual environment
python3 -m venv .venv
source .venv/bin/activate # Linux/macOS
# .venv\Scripts\activate # Windows PowerShell

# Install in editable mode
pip install --upgrade pip
pip install -e .
</syntaxhighlight>

Verify:
<syntaxhighlight lang="bash">
yolo help
</syntaxhighlight>

==== YOLOv8 Training Command ====
Train the nano model on your spectrogram dataset:
<syntaxhighlight lang="bash">
yolo detect train \
model=yolov8n.pt \
data=/content/dataset/data.yaml \
epochs=50 \
imgsz=640 \
batch=16 \
project=burst_train \
name=yolov8n_spectrogram
</syntaxhighlight>

'''Parameter notes:'''
* <code>model=yolov8n.pt</code> – Base architecture (nano).
* <code>data=...</code> – Path to <code>data.yaml</code>.
* <code>epochs=50</code> – Training epochs.
* <code>imgsz=640</code> – Input resolution.
* <code>batch=16</code> – Batch size.
* <code>project</code>/<code>name</code> – Output directories for logs/artifacts.

'''Outputs:'''
: <code>burst_train/yolov8n_spectrogram</code>
(Weights, logs, confusion matrices, PR curves, etc.)

== Conclusion ==
The NI RF Data Recording API provides a powerful and flexible framework for real-time spectrum sensing, dataset generation, and AI-driven signal classification across both x86 and embedded platforms such as NVIDIA Jetson.
By leveraging standardized formats like SigMF and integrating deep learning models such as YOLOv8, the framework enables a complete end-to-end workflow—from RF signal acquisition and metadata tagging to spectrogram creation, training, and live inference.

This modular approach allows researchers and engineers to rapidly prototype, evaluate, and deploy intelligent wireless sensing systems that bridge the gap between traditional SDR experimentation and modern AI-based spectrum analytics.
The same unified methodology can be extended to multi-band sensing, interference detection, cognitive radio, and 6G spectrum intelligence research, ensuring scalability and reproducibility in both laboratory and field environments.

[[Category:Application Notes]]