Quickstart

By following this guide, you can set up your private software-defined 5G network in an afternoon using the Sionna Research Kit. The system allows you to connect commercial off-the-shelf (COTS) user equipment (UE), either via cable or over-the-air.

Warning

Ensure compliance with local RF spectrum regulations before conducting over-the-air experiments.

Note

If you have your DGX Spark (DGX OS 7.3 or later) or Jetson (Jetpack R36.3 or later) system ready and if you are experienced with OAI, the shortest path to get started is:

# Checkout the Github repositorygitclone--recurse-submoduleshttps://github.com/NVlabs/sionna-rk.gitcdsionna-rk# Prepare systemmakeprepare-system# Rebootsudoreboot# Build Sionna RK images and configmakesionna-rk# You can now start the end-to-end system in the rf-simulator mode./scripts/start_system.shrfsim# Or connect your USRP and run real transmissions.# Note that you need to modify the .env file in the# config/b200/ directory to set your USRP serial number./scripts/start_system.shb200

What follows is a more detailed sequence of steps, including hardware configuration details.

Hardware Requirements

Overview of the deployed setup.

Fig. 16Overview of the deployed setup. SeeEttus OAI reference architecture for details.

Fig. 16 shows the setup of the Sionna Research Kit consisting of a USRP, a Quectel modem, and a DGX Spark. In the following, we will guide you through the steps to setup the system. The following components are required to run the Sionna Research Kit. Please refer to theBill of Materials for detailed specifications:

Connect the components as shown inFig. 16.This means that the DGX Spark is connected to the USRP and the Quectel modem is connected to the host machine. Connect the UE and the USRP via RF cables and corresponding splitters/combiners. Note that an attenuator in-between the USRP and the UE is strongly recommended to protect the USRP from high power levels.

Step 1: DGX Spark Setup

For DGX Spark, you need to install the latest DGX OS (7.3 or later).

If you want to run the Research Kit on the Jetson platform, please refer to theJetson AGX Orin Setup orJetson AGX Thor Setup setup guide.

Install the prerequisites:

sudoaptupdatesudoaptinstall-ygit

Clone the repository:

gitclone--recurse-submoduleshttps://github.com/NVlabs/sionna-rk.gitcdsionna-rk

Note

The following steps can also be executed via:

makeprepare-system

Configure the system:

./scripts/configure-system.shsudoreboot

For testing and development, create a virtual environment and install Python packages:

python3-mvenvenvsourceenv/bin/activatepipinstall-rrequirements.txt# pip install -r requirements_thor.txt for Thor# pip install -r requirements_orin.txt for Orin

[TODO] Add export lines for TensorRT

Step 2: USRP Setup

Install UHD drivers and verify the USRP connection:

# Run install script./scripts/install-usrp.sh# Verify connectionuhd_find_devicesuhd_usrp_probe

Note

Make note of your USRP’s serial number - you’ll need it later for configuration.

Note

Sometimes OAI gets confused if the USRP firmware is not loaded. In that case, run one of the uhd utilities to load the default firmware in the device, and retry.

Step 3: UE Setup

The next step is theSIM Card Programming.Connect the SIM card programmer, download theprogram_uicc tool fromhere and run the following commands:

# Note that the IMSI must be registered in config/common/oai_db.sql# numbers below are already pre-registered in the OAI databasesudo./program_uicc--adm12345678--imsi262990100016069\--keyfec86ba6eb707ed08905757b1bb44b8f\--opcC42449363BBAD02B66D16BC975D77CC1

Insert SIM card into the Quectel modem and configure the modem on the host machine (seeQuectel Modem Setup):

sudommcli-m0--enablesudonmclicaddtypegsmifnamecdc-wdm0con-nameoaiapnoaiconnection.autoconnectyes

Step 4: Deploy 5G Stack

5G Stack Overview

Fig. 17Overview of the deployed 5G end-to-end stack with IP adresses and interfaces of each container. Figure fromOpenAirInterface.

Fig. 17 shows the block diagram of the complete system (seeOpenAirInterface5G guide for more details). The 5G stack is deployed via Docker containers. The following steps build and deploy the core network components and the RAN components:

Note

The following steps can also be executed via:

makesionna-rk
# Pull, patch and build OAI containers./scripts/quickstart-oai.sh# Generate config files./scripts/generate-configs.sh# Build plugins specific components (e.g., TRT engines)./plugins/common/build_all_plugins.sh--host./plugins/common/build_all_plugins.sh--container

The system can be configured via environment variables. You can configure the system by editing the.env file in theconfig/b200/ orconfig/rfsim/ directory, respectively.

Editconfig/b200/.env and set the following parameters:

  • Set your USRP serial number

  • Select the configuration file for desired number of PRBs (default is 24, equals 8.64MHz bandwidth)

And finally, you can start the system:

# For real hardware setup using the USRP./scripts/start_system.shb200# Or for RF simulations without using real hardware./scripts/start_system.shrfsim

Monitor the system:

# Show running containersdockerps-a# View gNB logsdockerlogs-foai-gnb

The docker containers should be all in a “healthy” state and the gNB log shouldindicate that the UE is successfully connected (in-sync).

Have Your First Call

Congratulations, your system is now running and ready for your own experiments!

Verify connectivity on the host machine (using the Quectel modem):

# Check connection statusnmcliconnectionshow# Check that ip address is assigned to wwan0ipaddrshowwwan0# Test internet connectivity through the 5G tunnelping-Iwwan0google.com

This has been successfully tested on Raspberry Pi OS, for other distributions the Quectel QConnectManager might need to be installed manually.

Monitor system load:

# On DGX Sparknvtop# On Jetsonjtop

And run performance tests:

# If not already running, start iperf3 server in Docker containerdockerexec-doai-ext-dniperf3-s# On the client (UE); you need to install iperf3 on the host machine# Downlink testiperf3-u-t10-i1-b1M-B12.1.1.2-c192.168.72.135-R# Uplink testiperf3-u-t10-i1-b1M-B12.1.1.2-c192.168.72.135# Change 1M to the desired throughput in Mbit/s

You can now have your first call over your private 5G network!

We hope that you have enjoyed this quickstart guide! For inspiration and as blueprint for your own experiments, you can now try the following precompiled tutorials:

Check theTutorials page for more info.

For a detailed configuration and troubleshooting, see theSetup guide or visit theGithub Discussions.