maki/openairinterface5g
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Updated and enhanced channel simulation documentation

Browse Source 
- centralized channel simulation documentation in channel_simulation.md
- removed redundant documentation repeated in multipled .md files
- updated links
- removed obsolete information
- introduced mermaid flowchart for rfsim
- added missing information about available options and usage
- deleted:    ../../../openair1/SIMULATION/TOOLS/DOC/devusage.md
- deleted:    ../../../openair1/SIMULATION/TOOLS/DOC/rtusage.md
- deleted:    ../../../openair1/SIMULATION/TOOLS/DOC/arch.md

related to issue #739
This commit is contained in:
Guido Casati
2024-03-01 15:48:24 +01:00
parent 563109a88f
commit 4cfba89e68
8 changed files with 242 additions and 193 deletions
Download Patch File Download Diff File Expand all files Collapse all files
radio/rfsimulator/README.md
+38 -98
View File
@@ -12,6 +12,29 @@ 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).
# Architecture
High-level flowchart of the RF Simulator, including the channel simulation feature:
```mermaid
flowchart TD
subgraph ide1 [RX]
RU[ru_thread]-->|FH southbound|FH[rx_rf]
FH-->read
read -->|apply channel model|rxAddInput
end
subgraph ide2 [RFSim initialization]
A[load_lib] -->|load RFSIM lib| B[device_init]
B[device_init] -.-> |set trx_read_func|read[rfsimulator_read]
rxAddInput --> FH
B -->cfg[rfsimulator_readconfig]
cfg -->|read RFSIM CL options|C{rfsimu_params}
C -->|chanmod|loadchannel[load_channellist]
C -->|saviq|E[saveIQfile]
loadchannel-->|new SCM|scm[new_channel_desc_scm]
end
```
# Build
## From [build_oai](../../../doc/BUILD.md) script
@@ -44,46 +67,19 @@ default the RF simulator device will try to connect to host 127.0.0.1, port
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".
The RF simulator is using the configuration module, and its parameters are defined in a specific section called "rfsimulator". Add the following options to the command line in order to enable different RFSim features:
| parameter | usage | default |
|:---------------------|:------------------------------------------------------------------------------------------------------------------|----:|
| 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 |
| CL option | usage | default |
|:--------------------- |:-------------------------------------------------------------------------------|----: |
|`--rfsimulator.serveraddr <addr>`| ip address to connect to, or `server` to behave as a tcp server | 127.0.0.1 |
|`--rfsimulator.serverport <port>`| port number to connect to or to listen on (eNB, which behaves as a tcp server) | 4043 |
| `--rfsimulator.options` | list of comma separated run-time options, two are supported: `chanmod`, `saviq`| all options disabled |
| `--rfsimulator.options saviq` | store IQs to a file for future replay | disabled |
|`--rfsimulator.options chanmod` | enable the channel model | disabled |
|`--rfsimulator.IQfile <file>` | path to a file to store the IQ samples to (only with `saviq`) | `/tmp/rfsimulator.iqs` |
|`--rfsimulator.wait_timeout` | wait timeout when no UE is connected | 1 |
## 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 is
[`ci-scripts/conf_files/channelmod_rfsimu.conf`](../../ci-scripts/conf_files/channelmod_rfsimu.conf).
Add the following options to the command line to enable the channel model and the IQ samples saving for future replay:
```bash
--rfsimulator.options chanmod,saviq
```
or just:
```bash
--rfsimulator.options chanmod
```
to enable the channel model.
set the model with:
```bash
--rfsimulator.modelname AWGN
```
Example run:
```bash
sudo ./nr-softmodem -O ../../../targets/PROJECTS/GENERIC-LTE-EPC/CONF/gnb.band78.tm1.106PRB.usrpn300.conf --parallel-config PARALLEL_SINGLE_THREAD --rfsim --phy-test --rfsimulator.options chanmod --rfsimulator.modelname AWGN
```
where `@include "channelmod_rfsimu.conf"` has been added at the end of the file, and `ci-scripts/conf_files/channelmod_rfsimu.conf` copied to `targets/PROJECTS/GENERIC-LTE-EPC/CONF/`.
Please refer to this document [`SIMULATION/TOOLS/DOC/channel_simulation.md`](../../openair1/SIMULATION/TOOLS/DOC/channel_simulation.md) for information about using the RFSimulator options to run the simulator with a channel model.
## 4G case
@@ -133,9 +129,9 @@ sudo ./nr-uesoftmodem --rfsim --phy-test --rfsimulator.serveraddr <TARGET_GNB_IP
Notes:
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.
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_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).
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).
## Store and replay
@@ -152,65 +148,9 @@ 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
## How to use OAI RFSIM with a channel model
When the `chanmod` option is enabled, the RF channel simulator is called.
In the current version all channel parameters are set depending on the model name via a call to:
```bash
new_channel_desc_scm(bridge->tx_num_channels,
bridge->rx_num_channels,
<model name>,
bridge->sample_rate,
bridge->tx_bw,
0.0, // forgetting_factor
0, // maybe used for TA
0); // path_loss in dB
```
Only the input noise can be changed on command line with the `-s` parameter.
With path loss = 0 set `-s 5` to see a little noise. `-s` is a shortcut to `channelmod.s`. It is expected to enhance the channel modelization flexibility by the addition of more parameters in the channelmod section.
Example to add a very small noise:
```bash
-s 30
```
to add a lot of noise:
```bash
-s 5
```
Example run commands:
```bash
sudo ./nr-softmodem -O ../../../targets/PROJECTS/GENERIC-LTE-EPC/CONF/gnb.band78.tm1.106PRB.usrpn300.conf --parallel-config PARALLEL_SINGLE_THREAD --rfsim --phy-test --rfsimulator.options chanmod --rfsimulator.modelname AWGN
```
# Real time control and monitoring
Add the `--telnetsrv` option to the command line. Then in a new shell, connect to the telnet server, example:
```bash
telnet 127.0.0.1 9090
```
once connected it is possible to monitor the current status:
```bash
channelmod show current
```
see the available channel models:
```bash
channelmod show predef
```
or modify the channel model, for example setting a new model:
```bash
rfsimu setmodel AWGN
```
setting the pathloss, etc...:
```bash
channelmod modify <channelid> <param> <value>
channelmod modify 0 ploss 15
```
where `<param>` can be one of `riceanf`, `aoa`, `randaoa`, `ploss`, `offset`, `forgetf`.
Please refer to this document [`channel_simulation.md`](../../openair1/SIMULATION/TOOLS/DOC/channel_simulation.md) to get familiar with channel simulation in RFSIM and to see the list of commands for real-time usage with telnet.
# Caveats