Jaroslava Fiedlerova
888d4a91a6
add multi-ue support to vrtsim
Summary
Extending vrtsim to support multiple UEs with per-UE channel emulation using
CIRDB. Each UE can have different antenna configurations and independent
channel conditions (TDL models, delay spreads, and mobility speeds). This
includes:
- Add num_ues and ue_id parameters for server and client configuration
- Implement antenna offset multiplexing for UL combining and DL distribution
- Support heterogeneous antenna configurations across UEs (e.g., UE0: 1x2,
UE1: 2x2)
- Integrate CIRDB for per-UE channel modeling with independent TDL models,
delay spreads, and speeds
- Replace comma-separated per-UE params with structured ue_config blocks for
cleaner configuration
Usage:
* Start 5G core network
cd openairinterface5g/doc/tutorial_resources/oai-cn5g
docker-compose up -d
* Create network namespaces
sudo ip netns add ue0
sudo ip netns add ue1
* Start gNB (2x2 with multi-UE CIRDB)
sudo ./nr-softmodem -O ../../ci-scripts/conf_files/gnb.sa.band78.106prb.vrtsim.2x2.yaml --device.name vrtsim --vrtsim.role server --vrtsim.num_ues 2 --vrtsim.cirdb 1 --vrtsim.cirdb_file ~/raytracing-channel-emulator/server/external_taps/cir_db.bin --vrtsim.cirdb_yaml ~/raytracing-channel-emulator/server/external_taps/cir_db.yaml --vrtsim.ue_config.[0].antennas "1x2" --vrtsim.ue_config.[0].model_id 0 --vrtsim.ue_config.[0].ds_ns 10.0 --vrtsim.ue_config.[0].speed_mps 1.5 --vrtsim.ue_config.[1].antennas "2x2" --vrtsim.ue_config.[1].model_id 1 --vrtsim.ue_config.[1].ds_ns 30.0 --vrtsim.ue_config.[1].speed_mps 30.0
* Start UE 0 (1x2 antennas, TDL-A, 10ns DS, 1.5 m/s)
sudo ip netns exec ue0 ./nr-uesoftmodem -O ../../ci-scripts/conf_files/nrue.vrtsim.chanmod.yaml -C 3319680000 -r 106 --numerology 1 --ssb 516 --device.name vrtsim --vrtsim.role client --vrtsim.ue_id 0 --band 78 --ue-nb-ant-tx 1 --ue-nb-ant-rx 2 --uicc0.imsi 001010000000001
* Start UE 1 (2x2 antennas, TDL-B, 30ns DS, 30 m/s)
sudo ip netns exec ue1 ./nr-uesoftmodem -O ../../ci-scripts/conf_files/nrue.vrtsim.chanmod.yaml -C 3319680000 -r 106 --numerology 1 --ssb 516 --device.name vrtsim --vrtsim.role client --vrtsim.ue_id 1 --band 78 --ue-nb-ant-tx 2 --ue-nb-ant-rx 2 --uicc0.imsi 001010000000002
This document outlines how to use the OAI CI framework and gives a quickstart.
[[TOC]]
Quickstart
There is a script main.py that
- reads scenario files from XML
- executes the steps (e.g., deployment of CN/gNB/UE, attach, ping, ...)
To simplify, a script run_locally.sh can be used to run a single scenario
locally. First, download images for gNB&UE (we assume you already downloaded
the CN) and tag them "latest", which is expected by run_locally.sh:
docker pull oaisoftwarealliance/oai-gnb:develop
docker tag oaisoftwarealliance/oai-gnb:develop oai-gnb
docker pull oaisoftwarealliance/oai-nr-ue:develop
docker tag oaisoftwarealliance/oai-nr-ue:develop oai-nr-ue
Now, run the scenario:
cd ~/openairinterface5g/ci-scripts/
./run_locally.sh xml_files/container_5g_rfsim_simple.xml
Output should look like
[2025-08-07 18:07:49,631] INFO: ----------------------------------------
[2025-08-07 18:07:49,631] INFO: Creating HTML header
[2025-08-07 18:07:49,631] INFO: ----------------------------------------
[2025-08-07 18:07:49,766] INFO: ----------------------------------------
[2025-08-07 18:07:49,767] INFO: Starting Scenario: xml_files/container_5g_rfsim_simple.xml
[2025-08-07 18:07:49,767] INFO: ----------------------------------------
[2025-08-07 18:07:49,767] INFO: placing all artifacts for this run in /home/richie/oai/cmake_targets/log/container_5g_rfsim_simple.xml.d/
[...]
[2025-08-07 18:07:49,771] INFO: ----------------------------------------
[2025-08-07 18:07:49,771] INFO: Test ID: 1 (#1)
[2025-08-07 18:07:49,771] INFO: Deploy OAI 5G CoreNetwork
[2025-08-07 18:07:49,771] INFO: ----------------------------------------
it will run an end-to-end test, connecting one UE to the gNB, and ping, before
undeploying. As shown, logs will be under
/home/richie/oai/cmake_targets/log/container_5g_rfsim_simple.xml.d/. The
python code also produces an HTML report in ci-scripts/test_results.html.
Running with local changes
In order to run the tests as above, with local changes, please build images locally.
It is not yet possible to override an existing image with changes made locally to a source file and run it directly through the CI framework. However, it is possible to override an existing image with local changes, and run the scenario manually following the console logs steps provided above. This is described in the 5G RFsimulator README.