**Note: unless you know what you are doing, you likely do not need this!
Rather, you are probably looking for the
[RFsimulator](../radio/rfsimulator/README.md)!**
**Table of Contents**
oaisim has been scraped and replaced by the same programs that are used for the
real-time operation, `lte-softmodem` and `lte-uesoftmodem`. This uses the IF4p5
fronthaul protocol to achieve the communication.
[[_TOC_]]
The old oaisim is dead! Long live oaisim! :)
Context: oaisim used to be a simulation mode inside OAI to emulate an eNB and
multiple UEs.
If you are looking for a description of the old oaisim (which is still available in some branches/tags), please see [here](OpenAirLTEEmulation) and [here](how-to-run-oaisim-with-multiple-ue).
[[_TOC_]]
oaisim has been scraped and replaced by the same programs that are used for the real-time operation, `lte-softmodem` and `lte-uesoftmodem`. The latter also now includes an optional channel model, just like oaisim did.
# Build
# <a name="build">[How to build the eNB and the UE](BUILD.md)</a>
Build eNB/UE as normal, as also described in [How to build the eNB and the UE](./BUILD.md):
```bash
./build_oai -c--ninja--eNB--UE
```
The following paragraph explains how to run the L1 simulator in noS1 mode and using the oai kernel modules.
# How to run an eNB with the noS1 option
# <a name="run-noS1-eNB">How to run an eNB with the noS1 option</a>
The following paragraph(s) explains how to run the L1 simulator in noS1 mode and using the oai kernel modules.
Modify the configuration file for IF4p5 fronthaul, `/openairinterface5g/ci-scripts/conf_files/rcc.band7.nos1.simulator.conf`, and replace the loopback interface with a physical ethernet interface and the IP addresses to work on your network. Copy your modifications to a new file, let's call YYY.conf the resulting configuration file.
# <a name="run-noS1-UE">How to run a UE with the noS1 option</a>
# How to run a UE with the noS1 option
Similarly modify the example configuration file in `/openairinterface5g/ci-scripts/conf_files/rru.band7.nos1.simulator.conf` and replace loopback interface and IP addresses. Copy your modifications to a new file, let's call XXX.conf the resulting configuration file.
That should give you equivalent functionality to what you had with oaisim including noise and RF channel emulation (path loss / fading, etc.). You should also be able to run multiple UEs.
After you have [built the softmodem executables](BUILD.md) you can set your default directory to the build directory `cmake_targets/ran_build/build/` and start testing some use cases. Below, the description of the different oai functionalities should help you choose the oai configuration that suits your need.
This document explains some options for running 5G executables.
After you have [built the softmodem executables](BUILD.md) you can set your
default directory to the build directory `cmake_targets/ran_build/build/` and
start testing some use cases. Below, the description of the different OAI
functionalities should help you choose the OAI configuration that suits your
need.
[[_TOC_]]
...
...
@@ -20,28 +26,27 @@ After you have [built the softmodem executables](BUILD.md) you can set your defa
## RFsimulator
The RF simulator is an OAI device replacing the radio heads (for example the USRP device). It allows connecting the oai UE (LTE or 5G) and respectively the oai eNodeB or gNodeB through a network interface carrying the time-domain samples, getting rid of over the air unpredictable perturbations. This is the ideal tool to check signal processing algorithms and protocols implementation. The rf simulator has some preliminary support for channel modeling.
The RFsimulator is an OAI device replacing the radio heads (for example the
USRP device). It allows connecting the oai UE (LTE or 5G) and respectively the
oai eNodeB or gNodeB through a network interface carrying the time-domain
samples, getting rid of over the air unpredictable perturbations. This is the
ideal tool to check signal processing algorithms and protocols implementation.
The RFsimulator has some preliminary support for channel modeling.
It is planned to enhance this simulator with the following functionalities:
- Support for multiple eNodeB's or gNodeB's for hand-over tests
This is an easy use-case to setup and test, as no specific hardware is required. The [rfsimulator page](../radio/rfsimulator/README.md) contains the detailed documentation.
This is an easy use-case to setup and test, as no specific hardware is required. The [rfsimulator page](../radio/rfsimulator/README.md) contains the detailed documentation.
## L2 nFAPI Simulator
This simulator connects a eNodeB and UEs through a nfapi interface, short-cutting the L1 layer. The objective of this simulator is to allow multi UEs simulation, with a large number of UEs (ideally up to 255 ) .Here to ease the platform setup, UEs are simulated via a single `lte-uesoftmodem` instance. Today the CI tests just with one UE and architecture has to be reviewed to allow a number of UE above about 16. This work is on-going.
As for the rf simulator, no specific hardware is required. The [L2 nfapi simulator page](L2NFAPI.md) contains the detailed documentation.
## L1 Simulator
**This information might be outdated. We recommend to use the RFsimulator as
shown above.**
This simulator connects an eNodeB and UEs through an nFAPI interface,
short-cutting the L1 layer. The objective of this simulator is to allow multi
UEs simulation, with a large number of UEs (ideally up to 255).
The L1 simulator is using the ethernet fronthaul protocol, as used to connect a RRU and a RAU to connect UEs and a eNodeB. UEs are simulated in a single `lte-uesoftmodem` process, as for the nfapi simulator.
The [L1 simulator page](L1SIM.md) contains the detailed documentation.
As for the RFsimulator, no specific hardware is required. The [L2 nfapi
simulator page](./L2NFAPI.md) contains the detailed documentation.
# Running with a true radio head
...
...
@@ -89,7 +94,7 @@ At the UE the --sa flag will:
4) 5G-NR RRC Reconfiguration
5) Start Downlink and Uplink Data Transfer
Command line parameters for UE in --sa mode:
Command line parameters for UE in `--sa` mode:
-`-C` : downlink carrier frequency in Hz (default value 0)
-`--CO` : uplink frequency offset for FDD in Hz (default value 0)
-`--numerology` : numerology index (default value 1)
@@ -117,11 +122,15 @@ Additionally, at UE side `--uecap_file` option can be used to pass the UE Capabi
Some other useful paramters of the UE are
- --ue-fo-compensation: enables the frequency offset compenstation at the UE. This is useful when running over the air and/or without an external clock/time source
- --usrp-args: this is the equivalend paramter of sdr_addrs field in the gNB config file and can be used to identify the USRP and set some basic paramters (like the clock source)
- --clock-source: sets the clock-source (internal or external).
- --time-source: sets the time-source (internal or external).
-`--ue-fo-compensation`: enables the frequency offset compenstation at the UE. This is useful when running over the air and/or without an external clock/time source
-`--usrp-args`: this is the equivalend paramter of `sdr_addrs` field in the gNB config file and can be used to identify the USRP and set some basic paramters (like the clock source)
-`--clock-source`: sets the clock-source (internal or external).
-`--time-source`: sets the time-source (internal or external).
You can see all options by typing
```
./nr-uesoftmodem --help
```
# Specific OAI modes
...
...
@@ -154,9 +163,31 @@ In phy-test mode it is possible to mimic the reception of UE Capabilities at gNB
## noS1 setup with OAI UE
Instead of randomly generated payload, in the phy-test mode we can also inject/receive user-plane traffic over a TUN interface. This is the so-called noS1 mode.
Instead of randomly generated payload, in the phy-test mode we can also
inject/receive user-plane traffic over a TUN interface. This is the so-called
noS1 mode.
This setup is described in the [rfsimulator page](../radio/rfsimulator/README.md#5g-case). In theory this should also work with the real hardware target although this has yet to be tested.
The noS1 mode is applicable to both gNB/UE, and enabled by passing `--noS1` as
an option. The gNB/UE will open a TUN interface which the interface names and
IP addresses `oaitun_enb1`/10.0.1.1, and `oaitun_ue1`/10.0.1.2, respectively.
You can then use these interfaces to send traffic, e.g.,
```bash
iperf -sui1-B 10.0.1.2
```
to open an iperf server on the UE side, and
```bash
iperf -uc 10.0.1.2 -B 10.0.1.1 -i1-t10-b1M
```
to send data from the gNB down to the UE.
Note that this does not work if both interfaces are on the same host. We
recommend to use two different hosts, or at least network namespaces, to route
traffic through the gNB/UE tunnel.
This option is only really helpful for phy-test/do-ra (see below) modes, in
which the UE does not connect to a core network. If the UE connects to a core
network, it receives an IP address for which it automatically opens a network
interface.
## do-ra setup with OAI
...
...
@@ -244,7 +275,3 @@ The DL logical antenna port configuration can be selected through configuration
Finally the number of TX physical antenna in the RU part of the configuration file, `nb_tx`, should be equal or larger than the total number of PDSCH logical antenna ports.
[Example of configuration file with parameters for 2-layer MIMO](https://gitlab.eurecom.fr/oai/openairinterface5g/-/blob/develop/targets/PROJECTS/GENERIC-NR-5GC/CONF/gnb.sa.band77.fr1.273PRB.2x2.usrpn300.conf)
# Additional links
[Selecting an alternative ldpc implementation at run time](../openair1/PHY/CODING/DOC/LDPCImplementation.md)
This is an RF simulator that allows to test OAI without an RF board. It replaces an actual RF board driver.
As much as possible, it works like an RF board, but not in real-time: It can run faster than real-time if there is enough CPU, or slower (it is CPU-bound instead of real-time RF sampling-bound).
[[_TOC_]]
It can be run either in:
# General
- "noS1" mode: the generated IP traffic is sent and received between gNB and UE IP tunnel interfaces ("oaitun") by applications like ping and iperf
- "phy-test" mode: random UL and DL traffic is generated at every scheduling opportunity
This is an RF simulator that allows to test OAI without an RF board. It
replaces an actual RF board driver. In other words, towards the xNB/UE, it
behaves like a "real" RF board, but it forwards samples between both ends
instead of sending it over the air. It can simulate simple channels, such as
AWGN, hence it *simulates* RF.
As much as possible, it works like an RF board, but not in real-time: It can
run faster than real-time if there is enough CPU, or slower (it is CPU-bound
instead of real-time RF sampling-bound).
# build
# Build
## From [build_oai](../../../doc/BUILD.md) script
The RF simulator is implemented as an OAI device and always built when you build the OAI eNB or the OAI UE.
Using the `-w SIMU` option it is possible to just re-build the RF simulator device.
Using the `-w SIMU` option it is possible to just re-build the RF simulator device.
Example:
```bash
./build_oai --UE--eNB
Will compile UE
Will compile eNB
CMAKE_CMD=cmake ..
No local radio head and no transport protocol selected
No radio head has been selected (HW set to None)
No transport protocol has been selected (TP set to None)
RF HW set to None
Flags for Deadline scheduler: False
......................
......................
Compiling rfsimulator
Log file for compilation has been written to: /usr/local/oai/rfsimu_config/openairinterface5g/cmake_targets/log/rfsimulator.txt
rfsimulator compiled
......................
......................
./build_oai --UE--eNB--gNB--nrUE--ninja-w SIMU
```
## Add the rfsimulator after initial build
After any regular build you can compile the device from the build directory:
```bash
cd <path to oai sources>/openairinterface5g/cmake_targets/ran_build/build
make rfsimulator
ninja rfsimulator
```
This is equivalent to using `-w SIMU` when running the `build_oai` script.
# Usage
To use the RF simulator add the `--rfsim` option to the command line. By default the RF simulator device will try to connect to host 127.0.0.1, port 4043, which is usually the behavior for the UE.
## Overview
To use the RF simulator add the `--rfsim` option to the command line. By
default the RF simulator device will try to connect to host 127.0.0.1, port
4043, which is usually the behavior for the UE. For the eNB/gNB, you either
have to pass `--rfsimulator.serveraddr server` on the command line, or specify
the corresponding section in the configuration file.
The RF simulator is using the configuration module, and its parameters are defined in a specific section called "rfsimulator".
| serveraddr | ip address to connect to, or "enb" to behave as a tcp server | 127.0.0.1 |
| serveraddr | ip address to connect to, or `server` to behave as a tcp server | 127.0.0.1 |
| serverport | port number to connect to or to listen on (eNB, which behaves as a tcp server) | 4043 |
| options | list of comma separated run-time options, two are supported: `chanmod` to enable channel modeling and `saviq` to write transmitted iqs to a file | all options disabled |
| modelname | Name of the channel model to apply on received iqs when the `chanmod` option is enabled | AWGN |
| IQfile | Path to the file to be used to store iqs, when the `saviq` option is enabled | /tmp/rfsimulator.iqs |
## How to use the RF simulator options
To define and use a channel model, the configuration file needs to include a channel configuration file. To do this, add `@include "channelmod_rfsimu.conf"` to the end of the configuration file, and place the channel configuration file in the same directory. An example channel configuration file `channelmod_rfsimu.conf` is in `ci-scripts/conf_files`.
To define and use a channel model, the configuration file needs to include a
channel configuration file. To do this, add `@include "channelmod_rfsimu.conf"`
to the end of the configuration file, and place the channel configuration file
in the same directory. An example channel configuration file is
Add the following options to the command line to enable the channel model and the IQ samples saving for future replay:
```bash
...
...
@@ -69,7 +70,7 @@ or just:
```bash
--rfsimulator.options chanmod
```
to enable the channel model.
to enable the channel model.
set the model with:
```bash
...
...
@@ -86,16 +87,26 @@ where `@include "channelmod_rfsimu.conf"` has been added at the end of the file,
## 4G case
For the UE, it should be set to the IP address of the eNB. For example:
For the eNB, use a valid configuration file setup for the USRP board tests and start the softmodem with the `--rfsim` and `--rfsimulator.serveraddr server` options.
1. This starts the gNB and UE in the `phy-test` UP-only mode where the gNB is started as if a UE had already connected. See [RUNMODEM.md](../../doc/RUNMODEM.md) for more details.
2.<TARGET_GNB_INTERFACE_ADDRESS> can be 127.0.0.1 if both gNB and nrUE executables run on the same host, OR the IP interface address of the remote host running the gNB executable, if the gNB and nrUE run on separate hosts.
2.`<TARGET_GNB_IP_ADDRESS>` should be the IP interface address of the remote host running the gNB executable, if the gNB and nrUE run on separate hosts, or be omitted if they are on the same host.
3. To enable the noS1 mode, `--noS1` option should be added to the command line, see again [RUNMODEM.md](../../doc/RUNMODEM.md).
4. To operate the gNB/UE with a 5GC, start them using the `--sa` option. More information can be found [here](../../../doc/NR_SA_Tutorial_OAI_CN5G.md).
In the UE, you can add `-d` option to get the softscope.
Note: iperf tests can be performed only when running gNB and nrUE on separate hosts.
```
### Store and replay
## Store and replay
You can store emitted I/Q samples. If you set the option `saviq`, the simulator will write all the I/Q samples into this file. Then, you can replay with the executable `replay_node`.
...
...
@@ -163,7 +152,7 @@ The file format is successive blocks of a header followed by the I/Q array. If y
The format intends to be compatible with the OAI store/replay feature on USRP.
### Channel simulation
## Channel simulation
When the `chanmod` option is enabled, the RF channel simulator is called.
...
...
@@ -221,11 +210,8 @@ setting the pathloss, etc...:
channelmod modify <channelid> <param> <value>
channelmod modify 0 ploss 15
```
where:
```bash
<param name> can be one of "riceanf", "aoa", "randaoa", "ploss", "offset", "forgetf"
```
where `<param>` can be one of `riceanf`, `aoa`, `randaoa`, `ploss`, `offset`, `forgetf`.
# Caveats
Still issues in power control: txgain, rxgain are not used.
There are issues in power control: txgain/rxgain setting is not supported.
