Documentation update and small allignement of build_oai script -w option with documentation

cmake_targets/build_oai

@@ -728,7 +728,7 @@ function main() {
         echo_info "liboai_transpro.so is linked to ETHERNET transport"
       fi
 
-    if [ "$RFSIMULATOR" == "true" -o "$HW" == "OAI_SIMU" ] ; then
+    if [ "$HW" == "OAI_SIMU" ] ; then
         echo_info "Compiling rfsimulator"
         compilations \
             $lte_build_dir rfsimulator \

doc/BUILD.md

@@ -54,7 +54,7 @@ cd cmake_targets/
 ```
 
 - The `-I` option is to install pre-requisites, you only need it the first time you build the softmodem or when some oai dependencies have changed. 
-- The `-w` option is to select the radio head support you want to include in your build. Radio head support is provided via a shared library, which is called the "oai device" The build script creates a soft link from `liboai_device.so` to the true device which will be used at run-time (here the USRP one,`liboai_usrpdevif.so` . USRP is the only hardware tested today in the Continuous Integration process.
+- The `-w` option is to select the radio head support you want to include in your build. Radio head support is provided via a shared library, which is called the "oai device" The build script creates a soft link from `liboai_device.so` to the true device which will be used at run-time (here the USRP one,`liboai_usrpdevif.so` . USRP is the only hardware tested today in the Continuous Integration process. The RF simulator[RF simulator](../targets/ARCH/rfsimulator/README.md) is implemented as a specific device replacing RF hardware, it can be build using `-w SIMU` option.
 - `--eNB` is to build the `lte-softmodem` executable and all required shared libraries
 - `--UE` is to build the `lte-uesoftmodem` executable and all required shared libraries
 

targets/ARCH/rfsimulator/README.md

@@ -6,31 +6,52 @@ As much as possible, it works like a RF board, but not in realtime: it can run f
 
 #build
 
-## From build_oai
-You can build it the same way, and together with actual RF driver
+## From [build_oai](../../../doc/BUILD.md) script
+The RF simulator is implemented as an oai device and is always build 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 
 
 Example:
 ```bash
-./build_oai --ue-nas-use-tun --UE --eNB -w SIMU
+./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.Rel14.txt
+rfsimulator compiled
+......................
+......................
 ```
-It is also possible to build actual RF and use choose on each run:
-```bash
-./build_oai --ue-nas-use-tun --UE --eNB -w USRP --rfsimulator
-```
-Will build both the eNB (lte-softmodem) and the UE (lte-uesoftmodem)
-We recommend to use the option --ue-nas-use-tun that is much simpler to use than the OAI kernel driver.
 
 ## Add the rfsimulator after initial build
-After any regular build, you can compile the driver
+After any regular build, you can compile the device, from the build directory
 ```bash
-cd <the_compilation_dir_from_bouild_oai_script>/build
+cd <path to oai sources>/openairinterface5g/cmake_targets/lte_build_oai/build
 make rfsimulator
 ```
-Then, you can use it freely
+this is equivalent to using `-w SIMU` when running the `build_oai` script.
+e 
 
 # Usage
-Setting the env variable RFSIMULATOR enables the RF board simulator
-It should the set to "server" in the eNB or gNB
+To use the RF simulator you 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.
+The RF simulator is using the configuration module, its parameters are defined in a specific section called "rfsimulator"
+
+| parameter            | usage                                                                                                             | default |
+|:---------------------|:------------------------------------------------------------------------------------------------------------------|----:|
+| serveraddr           | ip address to connect to, or "enb" to behave as a tcp server                                                      | 127.0.0.1 |
+| serverport           | port number to connect to or to listen on (eNB, which behaved 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 |
+        
+Setting the env variable RFSIMULATOR can be used instead of using the serveraddr parameter, it is to preserve compatibility with previous version.
 
 ## 4G case
 For the UE, it should be set to the IP address of the eNB
@@ -38,13 +59,14 @@ example:
 ```bash
 sudo RFSIMULATOR=192.168.2.200 ./lte-uesoftmodem -C 2685000000 -r 50 
 ```
-Except this, the UE and the eNB can be used as it the RF is real
+Except this, the UE and the eNB can be used as it the RF is real. noS1 mode can also be used with the RF simulator.
 
-If you reach 'RA not active' on UE, be careful to generate a valid SIM
+If you reach 'RA not active' on UE, be careful to generate a valid SIM. 
 ```bash
 $OPENAIR_DIR/targets/bin/conf2uedata -c $OPENAIR_DIR/openair3/NAS/TOOLS/ue_eurecom_test_sfr.conf -o .
 ```
 ## 5G case
+5G RF simulator will be aligned with 4G as the effort to merge 5G specifuc branches into develop is making progress.
 After regular build, add the simulation driver
 (don't use ./build_oai -w SIMU until we merge 4G and 5G branches)
 ```bash
@@ -66,7 +88,7 @@ In UE, you can add "-d" to get the softscope
 
 You can store emitted I/Q samples:
 
-If you set the environment variable: saveIQfile to a file name
+If you set the option `saviq`
 The simulator will write all IQ samples into this file
 
 Then, you can replay with the executable "replay_node"
@@ -83,11 +105,11 @@ If you have existing stored I/Q, you can adpat the tool "replay_node" to convert
 The format intend to be compatible with the OAI store/replay feature on USRP
 
 ### Channel simulation
-The RF channel simulator is called.
-In current version all channel paramters are hard coded in the call to:
+When the `chanmod` option is enabled, The RF channel simulator is called.
+In current version all channel paramters are set depending on the model name via a call to:
 ```
 new_channel_desc_scm(bridge->tx_num_channels,bridge->rx_num_channels,
-                                          AWGN,
+                                          <model name>,
                                           bridge->sample_rate,
                                           bridge->tx_bw,
                                           0.0, // forgetting_factor
@@ -95,7 +117,7 @@ new_channel_desc_scm(bridge->tx_num_channels,bridge->rx_num_channels,
                                           0); // path_loss in dB
 ```
 Only the input noise can be changed on command line with -s parameter.
-With path loss = 0 set "-s 5" to see a little noise
+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 modedelization flexibility via the addition of more parameters in the channelmod section.
 
 #Caveacts
 Still issues in power control: txgain, rxgain are not used