Commit 2ef4dbe6 authored by Jaroslava Fiedlerova's avatar Jaroslava Fiedlerova

Merge remote-tracking branch 'origin/rfsimdoc' into integration_2024_w49 (!2392)

Documentation: add multi-UE deployment with RFsimulator

Extended doc/NR_SA_Tutorial_OAI_nrUE.md with section 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
parents 80736bb2 3438d45d
<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)
......@@ -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
......
[[_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:
......
......@@ -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:
```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
```
`--gNBs.[0].min_rxtxtime 6` is due to the UE not being able to handle shorter
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:
......
#!/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
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment