Add tutorial about how to run multiple UEs

* multiple UEs with namespaces (provided new script) * multiple UEs with Docker UEs * updated rfsimulator and channel simulation tutorials * updated README.md Co-authored-by: Arash Sahbafard <arash.sahbafard@silicon-austria.com>
2026-07-13 04:30:28 +00:00 · 2024-12-03 10:42:54 +01:00
parent 03946cd47b
commit 3438d45d6c
5 changed files with 255 additions and 11 deletions
--- a/doc/NR_SA_Tutorial_OAI_multi_UE.md
+++ b/doc/NR_SA_Tutorial_OAI_multi_UE.md
@@ -0,0 +1,119 @@
+<table style="border-collapse: collapse; border: none;">
+  <tr style="border-collapse: collapse; border: none;">
+    <td style="border-collapse: collapse; border: none;">
+      <a href="http://www.openairinterface.org/">
+         <img src="./images/oai_final_logo.png" alt="" border=3 height=50 width=150>
+         </img>
+      </a>
+    </td>
+    <td style="border-collapse: collapse; border: none; vertical-align: center;">
+      <b><font size = "5">OAI 5G NR SA tutorial to deploy multiple OAI nrUE</font></b>
+    </td>
+  </tr>
+</table>
+
+**Table of Contents**
+
+[[_TOC_]]
+
+# Scenario
+This tutorial is about how to configure and run multiple OAI nrUE in the same end-to-end OAI 5G setup with RFsimulator.
+
+# Pre-requisites
+
+This tutorial is assuming that OAI CN5G and OAI RAN are already deployed. To learn how to deploy and run a basic setup with OAI nrUE, please refer to [NR_SA_Tutorial_OAI_nrUE.md](NR_SA_Tutorial_OAI_nrUE.md).
+
+Also, it is suggested to get some knowledge on how the channel simulation with OAI RFsimulator works. Please refer to the following documentation to learn about the relevant topics discussed:
+
+- RFsimulator tutorial [rfsimulator/README.md](../radio/rfsimulator/README.md)
+- Channel simulation with OAI [channel_simulation.md](../openair1/SIMULATION/TOOLS/DOC/channel_simulation.md)
+- Telnet server usage [telnetusage.md](../common/utils/telnetsrv/DOC/telnetusage.md).
+
+# Run multiple UEs in RFsimulator
+
+## Multiple nrUEs with namespaces
+
+Important notes:
+
+* This should be run on the same host as the OAI gNB
+* Use the script [multi_ue.sh](../tools/scripts/multi-ue.sh) to make namespaces for multiple UEs.
+* For each UE, a namespace shall be created, each one has a different address that will be used as rfsim server address
+* Each UE shall have a different IMSI, which shall be present in the relevant tables of the MySQL database
+* Each UE shall run a telnet server on a different port, with command line option `--telnetsrv.listenport`
+
+1. For the first UE, create the namespace ue1 (`-c1`), then execute shell inside (`-o1`, "open"):
+
+   ```bash
+   sudo ./multi-ue.sh -c1
+   sudo ./multi-ue.sh -o1
+   ```
+
+2. After entering the bash environment, run the following command to deploy your first UE
+
+   ```bash
+   sudo ./nr-uesoftmodem -O ../../../targets/PROJECTS/GENERIC-NR-5GC/CONF/ue.conf -r 106 --numerology 1 --band 78 -C 3619200000    --rfsim --uicc0.imsi 001010000000001 --rfsimulator.options chanmod --rfsimulator.serveraddr 10.201.1.100 --telnetsrv    --telnetsrv.listenport 9095
+   ```
+
+3. For the second UE, create the namespace ue2 (`-c1`), then execute shell inside (`-o1`, "open"):
+
+   ```bash
+   sudo ./multi-ue.sh -c2
+   sudo ./multi-ue.sh -o2
+   ```
+
+4. After entering the bash environment, run the following command to deploy your second UE:
+
+   ```bash
+   sudo ./nr-uesoftmodem -O ../../../targets/PROJECTS/GENERIC-NR-5GC/CONF/ue.conf -r 106 --numerology 1 --band 78 -C 3619200000    --rfsim --uicc0.imsi 001010000000002 --rfsimulator.options chanmod --rfsimulator.serveraddr 10.202.1.100 --telnetsrv    --telnetsrv.listenport 9096
+   ```
+
+in the command above, please note that the IMSI and the telnet port changed.
+
+## Running Multiple UEs with Docker
+
+1. Make sure OAI nrUE image is pulled:
+
+   ```bash
+   docker pull oaisoftwarealliance/oai-nr-ue:latest
+   ```
+
+2. Configure your setup by editing the Docker compose file e.g. in [docker-compose.yaml](../ci-scripts/yaml_files/5g_rfsimulator/docker-compose.yaml).
+
+3. Deploy the UEs, e.g. for 3 UEs:
+
+   ```bash
+   docker compose up -d oai-nr-ue{1,2,3}
+   ```
+
+4. Check the logs to ensure each UE has gotten an IP address, e.g.:
+
+   ```bash
+   docker logs oai-nr-ue1
+   ```
+
+   or
+
+   ```bash
+   docker exec -it oai-nr-ue1 ip a show oaitun_ue1
+   ```
+
+5. Test the connectivity of each UE to the core network:
+
+   ```bash
+   docker exec -it oai-nr-ue1 ping -c1 192.168.70.135
+   ```
+
+7. After testing, undeploy the UEs to allow them time to deregister, and then bring down the rest of the network:
+
+   ```bash
+   docker compose stop oai-nr-ue{1,2,3}
+   docker compose down -v
+   ```
+
+# Further reading
+
+For more details and scenarios, refer to the following files:
+
+* [RFSIM deployment in the CI](../ci-scripts/yaml_files/5g_rfsimulator/README.md)
+* [E1 deployment in the CI](../ci-scripts/yaml_files/5g_rfsimulator_e1/README.md)
+* [Docker documentation](../docker/README.md)
--- a/doc/README.md
+++ b/doc/README.md
@@ -43,6 +43,7 @@ There is some general information in the [OpenAirInterface Gitlab Wiki](https://
  * [OAI 5GC](./NR_SA_Tutorial_OAI_CN5G.md)
  * [OAI gNB with COTS UE](./NR_SA_Tutorial_COTS_UE.md)
  * [OAI NR-UE](./NR_SA_Tutorial_OAI_nrUE.md)
+  * [Multiple OAI NR-UE with RFsimulator](./NR_SA_Tutorial_OAI_multi_UE.md)
 - [RUNMODEM.md](./RUNMODEM.md): Generic information on how to
  * Run simulators
  * Run with hardware
--- a/openair1/SIMULATION/TOOLS/DOC/channel_simulation.md
+++ b/openair1/SIMULATION/TOOLS/DOC/channel_simulation.md
@@ -1,5 +1,13 @@
 [[_TOC_]]

+This document is complementary to the [RFSIMULATOR Tutorial](../../../../radio/rfsimulator/README.md).
+
+# Channel Modeling
+
+Channel models in the context of wireless communication refer to mathematical models that simulate the effects of transmission mediums on signal propagation. These models account for factors such as attenuation, interference, and fading, which can affect the quality of communication between transmitter and receiver.
+
+Different channel models represent different real-world scenarios, such as urban environments, indoor spaces, or rural areas. By using these models, researchers and engineers can predict and evaluate the performance of wireless systems under various conditions.
+
 # OAI channel simulation feature

 OpenAirInterface RFSimulator incorporates a channel simulation feature. This feature allows any component to modify the time domain samples of a RF channel. It achieves this by applying predefined models, such as those defined in 3GPP TR 36.873 or TR 38.901.
@@ -8,7 +16,6 @@ The definition, configuration, and real-time modification of a channel model are

 The RFSimulator is the exclusive option that provides access to all the configuration and real-time modification features of OAI's channel simulation. This makes it a comprehensive tool for managing and manipulating channel simulations in OAI.

-
 # Implementation
 OAI channel simulation is using the [config module](../../../../common/config/DOC/config.md) to get its parameters at init time. The [telnet server](../../../../common/utils/telnetsrv/DOC/telnetsrv.md) includes a set of commands which can be used to dynamically modify some channel model parameters.

@@ -39,13 +46,22 @@ channel_desc_t *new_channel_desc_scm(uint8_t nb_tx,

 # Channel Model configuration file

-To define and use a channel model for uplink, the gNB configuration file needs to include a channel configuration file. To do this, add `@include "channelmod_rfsimu.conf"` at the end of the gNB configuration file, and place the channel configuration file in the same directory. The same shall be done for downlink by including the channel model configuration file at the end of UE configuration file (e.g. [`ci-scripts/conf_files/nrue.uicc.conf`](../../../../ci-scripts/conf_files/nrue.uicc.conf)).
+To define and use a channel model for uplink, the gNB configuration file needs to include a channel configuration file. To do this, add:
+
+```bash
+@include "channelmod_rfsimu.conf"
+```
+
+at the end of the gNB configuration file, and place the channel configuration file in the same directory. The same shall be done for downlink by including the channel model configuration file at the end of UE configuration file. E.g.
+
+* nrUE [`ci-scripts/conf_files/nrue.uicc.conf`](../../../../ci-scripts/conf_files/nrue.uicc.conf)
+* gNB [gnb.sa.band78.106prb.rfsim.conf](../../../../ci-scripts/conf_files/gnb.sa.band78.106prb.rfsim.conf)

 All channel simulation parameters are defined in the `channelmod` section. Most parameters are specific to a channel model and  are only used by the rfsimulator. An example of the configuration file can be found here:

 * [`ci-scripts/conf_files/channelmod_rfsimu.conf`](../../../../ci-scripts/conf_files/channelmod_rfsimu.conf)

-e.g.:
+e.g. a simple scenario to with an AWGN channel:

 ```bash
 channelmod = {
@@ -76,6 +92,29 @@ channelmod = {

 where `rfsimu_channel_ue0` will be activated on server side (i.e. eNB/gNB) for uplink and `rfsimu_channel_enB0` will be activated on client side (i.e. UE) for downlink.

+## Edit the configuration file
+
+How simulate noise of a AWGN channel? Starting from the configuration file in the previous section, in the `rfsimu_channel_enB0` model part, set the noise power to:
+
+```bash
+  noise_power_dB  = -10
+```
+
+In the `rfsimu_channel_ue0` model part, set the noise power to:
+```bash
+  noise_power_dB  = -20;
+```
+
+and the rest of the `channelmod_rfsimu.conf` remains unchanged.
+
+## Monitoring by nr-scope
+
+In order to verify the effects of the changes introduced by the channel simulation, the `nr-scope` constellation tool can be used to track and analyze the modulation constellation points. This tool allows users to visualize the modulation scheme being used and assess the quality of the received signals. By observing the constellation points, users can verify whether the changes made to the system configuration have resulted in.
+
+# Build the telnet server library
+
+Please refer to this documentation [telnetusage.md](../../../../common/utils/telnetsrv/DOC/telnetusage.md).
+
 # Run OAI with a channel model

 When the `chanmod` option is enabled, the RF channel simulator with a channel modeling function is called. Add the following options to the command line to enable the channel model:
--- a/radio/rfsimulator/README.md
+++ b/radio/rfsimulator/README.md
@@ -114,19 +114,37 @@ $OPENAIR_DIR/cmake_targets/ran_build/build/conf2uedata -c $OPENAIR_DIR/openair3/

 Similarly as for 4G, first launch the gNB, here in an example for the phytest:

-```bash
-sudo ./nr-softmodem -O ../../../targets/PROJECTS/GENERIC-LTE-EPC/CONF/gnb.band78.tm1.106PRB.usrpn300.conf --gNBs.[0].min_rxtxtime 6 --phy-test --rfsim --rfsimulator.serveraddr server
-```
+run gNB:

-`--gNBs.[0].min_rxtxtime 6` is due to the UE not being able to handle shorter
+  ```bash
+  sudo ./nr-softmodem -O ../../../targets/PROJECTS/GENERIC-LTE-EPC/CONF/gnb.band78.tm1.106PRB.usrpn300.conf --gNBs.[0].min_rxtxtime 6 --phy-test --rfsim --rfsimulator.serveraddr server
+  ```
+
+where `--gNBs.[0].min_rxtxtime 6` is due to the UE not being able to handle shorter
 RX/TX times.  As in the 4G case above, you can define an `rfsimulator` section
 in the config file.

-Then, launch the UE:
+and run UE:

-```bash
-sudo ./nr-uesoftmodem --rfsim --phy-test --rfsimulator.serveraddr <TARGET_GNB_IP_ADDRESS>
-```
+  ```bash
+  sudo ./nr-uesoftmodem --rfsim --phy-test --rfsimulator.serveraddr <TARGET_GNB_IP_ADDRESS>
+  ```
+
+To run OAI RFSimulator for SA mode, gNB:
+
+  ```bash
+  sudo ./nr-softmodem -O ../../../targets/PROJECTS/GENERIC-NR-5GC/CONF/gnb.sa.band78.fr1.106PRB.usrpb210.conf --rfsim --rfsimulator.serveraddr server
+  ```
+
+and UE:
+
+  ```bash
+  sudo ./nr-uesoftmodem --rfsim --rfsimulator.serveraddr <TARGET_GNB_IP_ADDRESS>
+  ```
+
+In the commands for the UE, `TARGET_GNB_IP_ADDRESS` can be 127.0.0.1 if both UE and gNB run on the same machine.
+
+If necessary the user can provide a custom UICC configuration file to the UE with command line option `-O ue.conf`. In case of a multi-UE scenario, the user shall provide a different IMSI to each UE with the command line option `--uicc0.imsi` followed by the IMSI, e.g. `--uicc0.imsi 001010000000001`.

 Notes:

--- a/tools/scripts/multi-ue.sh
+++ b/tools/scripts/multi-ue.sh
@@ -0,0 +1,67 @@
+#!/bin/bash
+
+ue_id=-1
+
+create_namespace() {
+  ue_id=$1
+  local name="ue$ue_id"
+  echo "creating namespace for UE ID ${ue_id} name ${name}"
+  ip netns add $name
+  ip link add v-eth$ue_id type veth peer name v-ue$ue_id
+  ip link set v-ue$ue_id netns $name
+  BASE_IP=$((200+ue_id))
+  ip addr add 10.$BASE_IP.1.100/24 dev v-eth$ue_id
+  ip link set v-eth$ue_id up
+  iptables -t nat -A POSTROUTING -s 10.$BASE_IP.1.0/255.255.255.0 -o lo -j MASQUERADE
+  iptables -A FORWARD -i lo -o v-eth$ue_id -j ACCEPT
+  iptables -A FORWARD -o lo -i v-eth$ue_id -j ACCEPT
+  ip netns exec $name ip link set dev lo up
+  ip netns exec $name ip addr add 10.$BASE_IP.1.$ue_id/24 dev v-ue$ue_id
+  ip netns exec $name ip link set v-ue$ue_id up
+}
+
+delete_namespace() {
+  local ue_id=$1
+  local name="ue$ue_id"
+  echo "deleting namespace for UE ID ${ue_id} name ${name}"
+  ip link delete v-eth$ue_id
+  ip netns delete $name
+}
+
+list_namespaces() {
+  ip netns list
+}
+
+open_namespace() {
+  if [[ $ue_id -lt 1 ]]; then echo "error: no last UE processed"; exit 1; fi
+  local name="ue$ue_id"
+  echo "opening shell in namespace ${name}"
+  echo "type 'ip netns exec $name bash' in additional terminals"
+  ip netns exec $name bash
+}
+
+usage () {
+  echo "$1 -c <num>: create namespace \"ue<num>\""
+  echo "$1 -d <num>: delete namespace \"ue<num>\""
+  echo "$1 -e      : execute shell in last processed namespace"
+  echo "$1 -l      : list namespaces"
+  echo "$1 -o <num>: open shell in namespace \"ue<num>\""
+}
+
+prog_name=$(basename $0)
+
+if [[ $(id -u) -ne 0 ]] ; then echo "Please run as root"; exit 1; fi
+if [[ $# -eq 0 ]]; then echo "error: no parameters given"; usage $prog_name; exit 1; fi
+
+while getopts c:d:ehlo: cmd
+do
+  case "${cmd}" in
+    c) create_namespace ${OPTARG};;
+    d) delete_namespace ${OPTARG};;
+    e) open_namespace; exit;;
+    h) usage ${prog_name}; exit;;
+    l) list_namespaces;;
+    o) ue_id=${OPTARG}; open_namespace;;
+    /?) echo "Invalid option"; usage ${prog_name}; exit;;
+  esac
+done