This document explains some options for running 5G executables.
This document is a general overview of running `nr-softmodem`, the OAI 5G
gNodeB executable. For build instructions see [BUILD.md](BUILD.md). For UE
documentation see [runmodem-nrue.md](runmodem-nrue.md).
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.
> **Note:** UE documentation previously found in this document has been moved
> to [a separate page](./runtmodem-nrue.md)
> **Note:** NTN-specific configuration steps previously found in this document
> have been moved to [a separate page](./ntn-configuration.md)
[[_TOC_]]
[[_TOC_]]
## Simulators
## Modes of operation
### RFsimulator
The RFsimulator is an OAI device replacing the radio heads (for example the
`nr-softmodem` supports several deployment modes. The default is "standalone"
USRP device). It allows connecting the oai UE (LTE or 5G) and respectively the
mode.
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:
| Option | Mode | Description |
|----------|------------|-------------|
| _none_ | standalone | Run gNB in SA mode (no flag). |
| `--nsa` | NSA | Non-standalone mode, requires an LTE eNB, see [NSA documentation](TESTING_OAI_NSA_COTS_UE.md). |
| phy-test | `--phy-test` | Test modes without random access, see [nrUE page](runmodem-nrue.md). |
| do-ra | `--do-ra` | Test mode without a core network or RRC connection, see [nrUE page](runmodem-nrue.md). |
| noS1 | `--noS1` | Manually inject traffic, suitable for phy-test/do-ra without core network. |
- Support for multiple eNodeB's or gNodeB's for hand-over tests
## Basic invocation
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.
From the build directory (with `build_oai`, by default `cmake_targets/ran_build/build/`):
### L2 nFAPI Simulator
```bash
sudo ./nr-softmodem -O <config_file> [options]
```
This simulator connects an eNodeB and UEs through an nFAPI interface,
Example with a USRP B210:
short-cutting the L1 layer. The objective of this simulator is to allow multi
```bash
UEs simulation, with a large number of UEs (ideally up to 255).
As for the RFsimulator, no specific hardware is required. The [L2 nfapi
CI-tested sample configuration files are in `ci-scripts/conf_files/`. Sample
simulator page](./L2NFAPI.md) contains the detailed documentation.
configuration files for various hardware can be found under
`targets/PROJECTS/GENERIC-NR-5GC/CONF/`.
## Running with a true radio head
## Configuration file
OAI supports different radio heads, the following are tested in the CI:
The configuration file can use either libconfig (`.conf`) or YAML (`.yaml`)
syntax, based on the file ending. The main sections are:
1.[Monolithic eNodeB](https://gitlab.eurecom.fr/oai/openairinterface5g/wikis/HowToConnectCOTSUEwithOAIeNBNew) where the whole signal processing is performed in a single process
For a reference of frequency parameters and band configurations see
[gNB frequency setup](gNB_frequency_setup.md).
### Security
The `security` section controls NAS/AS security algorithm selection:
The standalone mode is the default mode.
```
security = {
# preferred ciphering algorithms
# the first one of the list that an UE supports in chosen
# valid values: nea0, nea1, nea2, nea3
ciphering_algorithms = ( "nea0" );
# preferred integrity algorithms
# the first one of the list that an UE supports in chosen
# valid values: nia0, nia1, nia2, nia3
integrity_algorithms = ( "nia2", "nia0" );
# setting 'drb_ciphering' to "no" disables ciphering for DRBs, no matter
# what 'ciphering_algorithms' configures; same thing for 'drb_integrity'
drb_ciphering = "yes";
drb_integrity = "no";
};
```
Before tag `2024.w45`, the default mode was NSA. Thus, in the past, to run
## Common radio devices
either the gNB or the UE in standalone mode, it was necessary to provide the
`--sa` flag in the command line. This is not the case anymore. If provided
the softmodem exits reporting that it does not know this option.
The default (SA) mode does the following:
### RFsimulator
- At the gNB:
* The RRC encodes SIB1 according to the configuration file and transmits it through NR-BCCH-DL-SCH.
- At the UE:
The RFsimulator replaces the radio device with a virtual radio, allowing
* Decode SIB1 and starts the 5G NR Initial Access Procedure for SA:
gNB and UE to run without hardware. Built by default. Ideal for testing,
1) 5G-NR RRC Connection Setup
debugging, and development. Add `--rfsim` to the command line.
2) NAS Authentication and Security
3) 5G-NR AS Security Procedure
4) 5G-NR RRC Reconfiguration
5) Start Downlink and Uplink Data Transfer
### Other/Special modes to run with OAI NR-UE
See the [RFsimulator documentation](../radio/rfsimulator/README.md).
The gNB/nrUE support a number of special modes (phy-test, do-ra, noS1) that
### USRP (B2xx, N3xx, X3xx, x4xx)
cannot be used with COTS UE. As they specifically require the use of the OAI
nrUE, these modes are described [on the UE page](./runmodem-nrue.md).
### Common gNB and NR UE command line options
Build with `build_oai -w USRP`/`cmake -DOAI_USRP=ON`. The device is selected
automatically. Common per-device recommendations:
#### Three-quarter sampling
- B210: use `-E --continuous-tx`; limited to ~40 MHz bandwidth
- N3xx/X3xx: use `--usrp-tx-thread-config 1`; consider `--tune-offset` or
`ul_prbblacklist` for DC noise at high bandwidth
The command line option `-E` can be used to enable three-quarter sampling for split 8 sample rate. Required for certain radios (e.g., 40MHz with B210). If used on the gNB, it is a good idea to use for the UE as well (and vice versa).
For network tuning of 10G USRP devices (N300, X300):
```bash
sudo ethtool -G <ifname> tx 4096 rx 4096
sudo sysctl -w net.core.wmem_max=62500000
sudo sysctl -w net.core.rmem_max=62500000
```
#### Run OAI with SDAP & Custom DRBs
See also the [COTS UE tutorial](NR_SA_Tutorial_COTS_UE.md) and
SDAP is enabled by default. To disable SDAP, include `--gNBs.[0].enable_sdap 0` to the binary's arguments.
### O-RAN 7.2 Fronthaul (FHI)
The DRB creation is dependent on the 5QI.
For O-RAN split 7.2 with an O-RU, build with `build_oai -t
If the 5QI corresponds to a GBR Flow it assigns a dedicated data radio bearer.
oran_fhlib_5g`/`cmake -DOAI_FHI72=ON`. Configuration requires a `fhi_72`
The Non-GBR flows use a shared data radio bearer.
section and DPDK setup. See the [O-RAN FHI 7.2 tutorial](ORAN_FHI7.2_Tutorial.md).
To hardcode the DRBs for testing purposes, simply add `--gNBs.[0].drbs x` to the binary's arguements, where `x` is the number of DRBs, along with SDAP.
## Higher-layer splits
The hardcoded DRBs will be treated like GBR Flows. Due to code limitations at this point the max. number of DRBs is 4.
### IF setup with OAI
### CU/DU (F1) and CU-CP/CU-UP (E1) splits
OAI is also compatible with Intermediate Frequency (IF) equipment, allowing the
F1 splits the gNB into a CU (RRC/PDCP/SDAP) and one or more DUs (RLC/MAC/L1).
use of RF front-ends operating on arbitrary frequency bands that do not conform
See [F1AP docs](F1AP/F1-design.md). The CU and DU connect via F1AP over SCTP.
to the standardized 3GPP NR bands.
The DU configuration specifies the CU IP address.
### OAIUE configuration
To run a split gNB, start a CU and one or more DUs separately:
To configure IF frequencies on the UE side, provide the following command-line
options:
-`if_freq`: DL frequency in Hz
-`if_freq_off`: UL frequency offset in Hz
### gNB configuration
```bash
On the gNB side, the corresponding parameters must be set in the RUs section of
between both. It is further possible use networked FAPI (nFAPI) to separate L1
```
and L2 into separate processes on different hosts and use socket-based
communication. See the [FAPI/nFAPI documentation](nfapi.md)
## 5G gNB MIMO configuration
## 5G gNB MIMO configuration
...
@@ -157,3 +264,19 @@ Finally the number of TX physical antenna in the RU part of the configuration fi
...
@@ -157,3 +264,19 @@ Finally the number of TX physical antenna in the RU part of the configuration fi
It is possible to limit the number supported DL MIMO layers via RRC configuration, e.g. to a value lower than the number of logical antenna ports configured, by using the configuration file parameter `maxMIMO_layers`.
It is possible to limit the number supported DL MIMO layers via RRC configuration, e.g. to a value lower than the number of logical antenna ports configured, by using the configuration file parameter `maxMIMO_layers`.
[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)
[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)
## IF (Intermediate Frequency) equipment
OAI supports RF front-ends operating on arbitrary frequencies outside standard
3GPP NR bands. Configure in the `RUs` section of the gNB config file:
-`if_freq`: DL frequency in Hz (suffix with `L` in libconfig, e.g. `2169080000L`)
-`if_offset`: UL frequency offset in Hz
## Related documentation
Further documentation not referenced above:
-[Build instructions](BUILD.md)
-[NR SA tutorial with OAI nrUE](NR_SA_Tutorial_OAI_nrUE.md)
