---
title: 'Project documentation template'
disqus: hackmd
---
OAI 5G SA Testbed Setup Guide
===
## Table of Contents
[TOC]
## Beginners Guide
If you are a total beginner to OpenAirInterface, start here!
1. Visit [OAI wiki](https://gitlab.eurecom.fr/oai/openairinterface5g/-/wikis/home) to understand the capabilities of OAI
2. If you know what is OAI and want to setup the testbed: Visit [GitLab OAI for NR_SA_CN5G_gNB_USRP_COTSUE_Tutorial](https://gitlab.eurecom.fr/oai/openairinterface5g/-/blob/develop/doc/NR_SA_CN5G_gNB_USRP_COTS_UE_Tutorial.md) and read the whole tutorial.
3. If you have the necessary hardware to build the testbed, then you are ready!
Core Network Setup
---
#### 1) Installing Dependencies
First, install the necessary dependencies for OAI 5G CN.
```
sudo apt install -y git net-tools putty
sudo apt install -y apt-transport-https ca-certificates curl software-properties-common
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"
sudo apt update
sudo apt install -y docker docker-ce
# Add your username to the docker group, otherwise you will have to run in sudo mode.
sudo usermod -a -G docker $(whoami)
reboot
# https://docs.docker.com/compose/install/
sudo curl -L "https://github.com/docker/compose/releases/download/v2.12.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose
```
#### 2) Get the source code of OAI CN
Pull the docker images with using following code in terminal.
```
# Git oai-cn5g-fed repository
git clone https://gitlab.eurecom.fr/oai/cn5g/oai-cn5g-fed.git ~/oai-cn5g-fed
# Pull docker images
docker pull oaisoftwarealliance/oai-amf:develop
docker pull oaisoftwarealliance/oai-nrf:develop
docker pull oaisoftwarealliance/oai-smf:develop
docker pull oaisoftwarealliance/oai-udr:develop
docker pull oaisoftwarealliance/oai-udm:develop
docker pull oaisoftwarealliance/oai-ausf:develop
docker pull oaisoftwarealliance/oai-spgwu-tiny:develop
docker pull oaisoftwarealliance/trf-gen-cn5g:latest
# Tag docker images
docker image tag oaisoftwarealliance/oai-amf:develop oai-amf:develop
docker image tag oaisoftwarealliance/oai-nrf:develop oai-nrf:develop
docker image tag oaisoftwarealliance/oai-smf:develop oai-smf:develop
docker image tag oaisoftwarealliance/oai-udr:develop oai-udr:develop
docker image tag oaisoftwarealliance/oai-udm:develop oai-udm:develop
docker image tag oaisoftwarealliance/oai-ausf:develop oai-ausf:develop
docker image tag oaisoftwarealliance/oai-spgwu-tiny:develop oai-spgwu-tiny:develop
docker image tag oaisoftwarealliance/trf-gen-cn5g:latest trf-gen-cn5g:latest
```
#### 3)Network Configuration
Execute the following commands to configure the network.
```
sudo sysctl net.ipv4.conf.all.forwarding=1
sudo iptables -P FORWARD ACCEPT
```
#### 4) OAI CN5G Configuration files
Download and copy the configuration files
Copy [docker-compose-basic-nrf.yaml](https://gitlab.eurecom.fr/oai/openairinterface5g/-/blob/develop/doc/tutorial_resources/docker-compose-basic-nrf.yaml) to ~/oai-cn5g-fed/docker-compose
```
wget -O ~/oai-cn5g-fed/docker-compose/docker-compose-basic-nrf.yaml https://gitlab.eurecom.fr/oai/openairinterface5g/-/raw/develop/doc/tutorial_resources/docker-compose-basic-nrf.yaml?inline=false
```
Then, copy [oai_db.sql](https://gitlab.eurecom.fr/oai/openairinterface5g/-/blob/develop/doc/tutorial_resources/oai_db.sql) to ~/oai-cn5g-fed/docker-compose/database
```
wget -O ~/oai-cn5g-fed/docker-compose/database/oai_db.sql https://gitlab.eurecom.fr/oai/openairinterface5g/-/raw/develop/doc/tutorial_resources/oai_db.sql?inline=false
```
The location of these configuration files might change in time. Check OAI gitlab to find the right links in case these links are not valid.
gNB Setup
---
#### 1) Build UHD to run USRP
```
sudo apt install -y libboost-all-dev libusb-1.0-0-dev doxygen python3-docutils python3-mako python3-numpy python3-requests python3-ruamel.yaml python3-setuptools cmake build-essential
git clone https://github.com/EttusResearch/uhd.git ~/uhd
cd ~/uhd
git checkout v4.3.0.0
cd host
mkdir build
cd build
cmake ../
make -j $(nproc)
make test # This step is optional
sudo make install
sudo ldconfig
sudo uhd_images_downloader
```
#### 2) Build OAI gNB
```
# Get openairinterface5g source code
git clone https://gitlab.eurecom.fr/oai/openairinterface5g.git ~/openairinterface5g
cd ~/openairinterface5g
git checkout develop
# Install OAI dependencies
cd ~/openairinterface5g
source oaienv
cd cmake_targets
./build_oai -I
# Build OAI gNB
cd ~/openairinterface5g
source oaienv
cd cmake_targets
./build_oai -w USRP --ninja --nrUE --gNB --build-lib all -c
```
If you get error on running "build_oai", put "**sudo**" in front of ./build_oai.
Now OAI is installed. It is good to pull the latest repo time to time to catch up with the latest release. If you pull, don’t forget to build again.
```
cd openairinterface5g
git checkout develop
git pull
source oaienv
git cmake_targets
sudo ./build_oai -w USRP --ninja --nrUE --gNB --build-lib all -c
```
GNB is all set. The rest would be configuring the USRP files and network.
#### 3) Network settings to reach the core
Add an IP-route to the core network:
```
sudo ip route add 192.168.70.128/26 via <IP_OF_THE_CORE_NETWORK_HOST_MACHINE>`
```
Now gNB is ready to use!
#### 4) Extra Notes for how to use config files
In the folder ***openairinterface/targets/PROJECTS/GENERIC-NR-5GC/CONF*** there are many config files to use for different cases. There are couple of important points to check.
FIrst, you need to check three files if the configuration inside these files are matching or not.
1. /oai-cn5g-fed/docker-compose/docker-compose-basic-nrf.yaml
2. ~/oai-cn5g-fed/docker-compose/database/oai_db.sql
3. And the .conf file that you will use while starting the base station Example:*openairinterface/targets/PROJECTS/GENERIC-NR-5GC/CONF/gnb.sa.band77.fr1.273PRB.2x2.usrpn300.con*f
Then check the following parameters:
* PLMN List
Make sure that plmn list settings are matching with what your core network configurations
An example: *openairinterface/targets/PROJECTS/GENERIC-NR-5GC/CONF/gnb.sa.band77.fr1.273PRB.2x2.usrpn300.conf* :
```
plmn_list = ({ mcc = 001; mnc = 01; mnc_length = 2; snssaiList = ({ sst = 1; sd = 0x1; }); });
```
* AMF Parameters
Make sure that plmn list settings are matching with what your core network configurations.
An example: ***openairinterface/targets/PROJECTS/GENERIC-NR-5GC/CONF/gnb.sa.band77.fr1.273PRB.2x2.usrpn300.conf*** :
```
////////// AMF parameters:
amf_ip_address = (
{
ipv4 = "192.168.70.132";
ipv6 = "192:168:30::17";
active = "yes";
preference = "ipv4";
}
);
NETWORK_INTERFACES :
{
GNB_INTERFACE_NAME_FOR_NG_AMF = "demo-oai";
GNB_IPV4_ADDRESS_FOR_NG_AMF = "192.168.70.129/24";
GNB_INTERFACE_NAME_FOR_NGU = "demo-oai";
GNB_IPV4_ADDRESS_FOR_NGU = "192.168.70.129/24";
GNB_PORT_FOR_S1U = 2152; # Spec 2152
}
```
#### 5) Advance Configurations
1. USRP X300 not found problem
Apply the following command in terminal in case your USRP X310 is not available after you checked it with "usrp_find_devices"
```
sudo iptables -A INPUT -p udp --sport 49152 -j ACCEPT
```
2) USRP N300 and X300 Ethernet Tuning
Please also refer to the official USRP Host Performance Tuning Tips and Tricks tuning guide.
The following steps are recommended. Please change the network interface(s) as required. Also, you should have 10Gbps interface(s): if you use two cables, you should have the XG interface. Refer to the N300 Getting Started Guide for more information.
• Use an MTU of 9000: how to change this depends on the network management tool. In the case of Network Manager, this can be done from the GUI.
To change the MTU size of an interface, use the following syntax:
```
ifconfig <Interface_name> mtu <mtu_size> up
```
For instance, to change the MTU size of an interface named ***ens4f0*** to 9000 bytes, the command would be:
```
ifconfig ens4f0 mtu 9000 up
```
• Increase the kernel socket buffer (also done by the USRP driver in OAI)
• Increase Ethernet Ring Buffers: sudo ethtool -G <ifname> rx 4096 tx 4096
• Disable hyper-threading in the BIOS (This step is optional)
• Optional: Disable KPTI Protections for Spectre/Meltdown for more performance. This is a security risk. Add mitigations=off nosmt in your grub config and update grub. (This step is optional)
Example code to run:
```
for ((i=0;i<$(nproc);i++)); do sudo cpufreq-set -c $i -r -g performance; done
sudo sysctl -w net.core.wmem_max=62500000
sudo sysctl -w net.core.rmem_max=62500000
sudo sysctl -w net.core.wmem_default=62500000
sudo sysctl -w net.core.rmem_default=62500000
sudo ethtool -G enp1s0f0 tx 4096 rx 4096
```
3) Real-time performance workarounds
• Enable Performance Mode in Ubuntu 22:
• Settings/Power/Power Mode: Performance
• If you get real-time problems on heavy UL traffic, reduce the maximum UL MCS using an additional command-line switch: --MACRLCs.[0].ul_max_mcs 14.
4) Uplink issues related with noise on the DC carriers
• There is noise on the DC carriers on N300 and especially the X300 in UL. To avoid their use or shift them away from the center to use more UL spectrum, use the --tune-offset <Hz> command line switch, where <Hz> is ideally half the bandwidth, or possibly less.
UE Setup
---
#### Instructions for Quectel:
First step is getting familiar with the device and following the tutorials coming with USB inside the packaging.
For windows there are some specific tools to use this Quectel 5g modems, and this tutorial does not include information for Windows set up. Follow the documents inside the Usb and use google to get it done for Windows.
For Linux, it seems easier than Windows. After setting up the M2 board and connecting the Modem to board and also the antennas, Use type C cable to power up the board (Use J0601)
Then, turn on both switches. First, turn the switch S0201 on, then turn on the switch S0101. After some time, you need to see the red and green leds ON.
If you think that your board looks like this pic, you can move forward :)
We will handle the commanding this board from Terminal. However, if you like to use a different way, check and search “quectel-CM” and download to Linux.
I used AT commands to control the device.
1) Download minicom for linux. We need a tool to command via Serial Port. I used minicom, I guess PuTTY and couple of more tools will do the same.
```
sudo apt update
sudo apt install minicom
```
The next step for minicom is openning a terminal and:
```
sudo minicom -D /dev/ttyUSB2
```
You need to see something like following.
```
Welcome to minicom 2.7.1
OPTIONS: I18n
Compiled on Dec 23 2019, 02:06:26.
Port /dev/ttyUSB2, 11:03:46
Press CTRL-A Z for help on special keys
```
Now you can apply AT commands. First, type ATI and enter to see the Model number of Quectel.
```
ATI
Quectel
RM500Q-GL
Revision: RM500QGLABR11A06M4G
```
Check the pdf that comes with the USB driver, to see all the AT commands.
```
# MUST be sent at least once everytime there is a firmware upgrade!
AT+QMBNCFG="Select","ROW_Commercial"
AT+QMBNCFG="AutoSel",0
AT+CFUN=1,1
# wait for reboot after CFUN command and then do the rest.
AT+CGDCONT=1,"IP","oai"
AT+CGDCONT=2
AT+CGDCONT=3
# The rest is after connecting to the gNB
# (Optional, debug only, AT commands) Activate PDP context, retrieve IP address and test with ping
AT+CGACT=1,1
AT+CGPADDR=1
AT+QPING=1,"openairinterface.org"
```
After gNB is On, use it to reboot the UE so it can connect to base station.
```
AT+CFUN=1,1
```
Sim Card Setup
---
#### 1)Sim Card Programmer pySim
https://osmocom.org/projects/pysim/wiki
(Only for installing pysim and how to use. After installing pysim, come back to this tutorial and follow from step 5)
Always better to do this process from website since they update it. However, just in case, the way that applied on this setup is as followed:
1) Open a terminal
```
sudo apt-get install --no-install-recommends \
pcscd libpcsclite-dev \
python3 \
python3-setuptools \
python3-pyscard \
python3-pip
pip3 install --user -r requirements.txt
```
2) Check the status of connection by entering the following command:
```
pcsc_scan
```
3) Get the code of PySIM by entering command:
```
git clone https://gitea.osmocom.org/sim-card/pysim
cd pysim
# Read the sim card
./pySim-read.py -p0 #or ./pySim-read.py -p1
```
4) Check which systems are added on your simcard from read command
5) Apply pysim shell to change the services for 5g
```
./pySim-shell.py -p 0
#Verify your ADM
pySIM-shell (MF)> verify_adm XXXXXXXX
# Activate or deactivate Service
pySIM-shell (MF)> select MF
pySIM-shell (MF)> select ADF.USIM
pySIM-shell (MF/ADF.USIM)> select EF.UST
# For Activate: pySIM-shell (MF/ADF.USIM/EF.UST)> ust_service_deactivate 124
#For Deactivate: pySIM-shell (MF/ADF.USIM/EF.UST)> ust_service_activate 124
```
124 is just for an example. You can check the service code with read command that provided on step 3.
In order to work with OAI, we have to deactivate service 124 otherwise gnB kicks our UE in 20 seconds. So apply :
```
pySIM-shell (MF/ADF.USIM/EF.UST)>ust_service_deactivate 124
```
6) Now we can program our card. I will give an example how to program the sim card however in order to apply it for your case, change the values for your situation.
Get the data for your specific simcard from SIMCARD_INFO_SYSMOCOM_IHP.pdf
```
cd pysim
./pySim-prog.py --pcsc-device=0 -j 0 --type="sysmoISIM-SJA2" --name=OpenAirInterface --mcc=001 --mnc=01 --imsi=001010000000001 --opc=C42449363BBAD02B66D16BC975D77CC1 --ki=fec86ba6eb707ed08905757b1bb44b8f --iccid=8988211000000649619 --pin-adm=71811917 --acc=0002
```
PS: MCC and MNC works when they are 001 and 01 for all types of modems or phones.
RUN the Testbed
---
Now everything is ready to have our 5G Network.
#### Start the Core Network in a terminal
```
cd ~/oai-cn5g-fed/docker-compose
python3 core-network.py --type start-basic --scenario 1
```
#### Start the gNB in another terminal
for USRP B210
```
cd ~/openairinterface5g
source oaienv
cd cmake_targets/ran_build/build
sudo ./nr-softmodem -O ../../../targets/PROJECTS/GENERIC-NR-5GC/CONF/gnb.sa.band78.fr1.106PRB.usrpb210.conf --sa -E --continuous-tx
```
for USRP N300
```
cd ~/openairinterface5g
source oaienv
cd cmake_targets/ran_build/build
sudo ./nr-softmodem -O ../../../targets/PROJECTS/GENERIC-NR-5GC/CONF/gnb.sa.band77.fr1.273PRB.2x2.usrpn300.conf --sa --usrp-tx-thread-config 1
```
for USRP X300
```
cd ~/openairinterface5g
source oaienv
cd cmake_targets/ran_build/build
sudo ./nr-softmodem -O ../../../targets/PROJECTS/GENERIC-NR-5GC/CONF/gnb.sa.band77.fr1.273PRB.2x2.usrpn300.conf --sa --usrp-tx-thread-config 1 -E --continuous-tx
```
#### Run UE
```
sudo minicom -D /dev/ttyUSB2
AT+CFUN=1,1
```
Now UE should be connected to GNB and you should see the log from gNB and CoreNetwork that UE is connected.
## Reference Links
[Cosa-5g-private-campus-network-deployment-oai](https://git.mylab.th-luebeck.de/5g/cosa-5g-private-campus-network-deployment-oai)
[Profile PowderTeam/oai-indoor-ota](https://www.powderwireless.net/show-profile.php?project=PowderTeam&profile=oai-indoor-ota)
[Sysmocom Manual](https://www.sysmocom.de/manuals/sysmousim-manual.pdf)
[SimCard Config Reference](https://gist.github.com/mrlnc/01d6300f1904f154d969ff205136b753)
[NorthEastern University OAI Testbed](https://openairx-labs.northeastern.edu/deploying-oai-in-5g-standalone-mode/
)
## Appendix and FAQ
Sign in with Wallet
Connect another wallet