TESTING_GNB_W_COTS_UE.md 13.7 KB
Newer Older
Remi Hardy's avatar
Remi Hardy committed
1
STATUS 2020/09/10 : updated the status of interop (end to end UL/DL traffic)  
Remi Hardy's avatar
Remi Hardy committed
2

Remi Hardy's avatar
Remi Hardy committed
3

Remi Hardy's avatar
Remi Hardy committed
4 5 6 7 8 9 10 11 12 13 14
## Table of Contents ##

1.   [Configuration Overview](#configuration-overview)
2.   [SW Repository / Branch](#repository)
3.   [Architecture Setup](#architecture-setup)
4.   [Build / Install](#build-and-install)
5.   [Run / Test](#run-and-test)
6.   [Test case](#test-case)
7.   [Log file monitoring](#log-file-monitoring)
6.   [Required tools for debug](#required-tools-for-debug)
7.   [Status of interoperability](#status-of-interoperability) 
15
8.   [CI integration](#ci-integration)  
Remi Hardy's avatar
Remi Hardy committed
16 17

## Configuration Overview
Remi Hardy's avatar
Remi Hardy committed
18 19 20 21 22 23

* Non Standalone (NSA) configuration  : initial Control Plane established between UE and RAN eNB, then User Plane established between UE and gNB, Core network is 4G based supporting rel 15

* Commercial UE: Oppo Reno 5G
* OAI Software Defined gNB and eNB
* eNB RF front end: USRP (ETTUS) B200 Mini or B210
Remi Hardy's avatar
Remi Hardy committed
24
* gNB RF front end: USRP (ETTUS) B200 Mini or B210 (N310 will be needed for MIMO and wider BW's)
Remi Hardy's avatar
Remi Hardy committed
25 26 27 28 29
* 5G TDD duplexing mode
* 5G FR1 Band n78 (3.5 GHz)
* BW: 40MHz
* Antenna scheme: SISO

Remi Hardy's avatar
Remi Hardy committed
30
## Repository
Remi Hardy's avatar
Remi Hardy committed
31 32 33 34 35

https://gitlab.eurecom.fr/oai/openairinterface5g/tree/develop

## Architecture Setup

Remi Hardy's avatar
Remi Hardy committed
36
The scheme below depicts our typical setup:
Remi Hardy's avatar
Remi Hardy committed
37

Remi Hardy's avatar
Remi Hardy committed
38
![image info](./testing_gnb_w_cots_ue_resources/oai_fr1_setup.jpg)
Remi Hardy's avatar
Remi Hardy committed
39

Remi Hardy's avatar
Remi Hardy committed
40 41 42
The photo depicts the FR1 setup part of the scheme above:  


Remi Hardy's avatar
Remi Hardy committed
43
![image info](./testing_gnb_w_cots_ue_resources/oai_fr1_lab.jpg)
Remi Hardy's avatar
Remi Hardy committed
44

Remi Hardy's avatar
Remi Hardy committed
45
## Build and Install
Remi Hardy's avatar
Remi Hardy committed
46

Remi Hardy's avatar
Remi Hardy committed
47
General guidelines to build eNB and gNB :
Remi Hardy's avatar
Remi Hardy committed
48 49 50
See https://gitlab.eurecom.fr/oai/openairinterface5g/blob/develop/doc/BUILD.md#building-ues-enodeb-and-gnodeb-executables


Remi Hardy's avatar
Remi Hardy committed
51
- **eNB**
Remi Hardy's avatar
Remi Hardy committed
52 53

```
Remi Hardy's avatar
Remi Hardy committed
54 55 56 57 58
cd <your oai installation directory>/openairinterface5g/
source oaienv
cd cmake_targets/
./build_oai -I -w USRP --eNB

Remi Hardy's avatar
Remi Hardy committed
59 60
```

Remi Hardy's avatar
Remi Hardy committed
61
- **gNB**
Remi Hardy's avatar
Remi Hardy committed
62 63

```
Remi Hardy's avatar
Remi Hardy committed
64 65 66 67
cd <your oai installation directory>/openairinterface5g/
source oaienv
cd cmake_targets/
./build_oai -I -w USRP --gNB
Remi Hardy's avatar
Remi Hardy committed
68 69
```

Remi Hardy's avatar
Remi Hardy committed
70 71 72 73

- **EPC**

for reference:
hardy's avatar
hardy committed
74
https://github.com/OPENAIRINTERFACE/openair-epc-fed/blob/master/docs/DEPLOY_HOME.md
Remi Hardy's avatar
Remi Hardy committed
75 76 77



Remi Hardy's avatar
Remi Hardy committed
78
## Configuration Files
Remi Hardy's avatar
Remi Hardy committed
79

Remi Hardy's avatar
Remi Hardy committed
80 81
Each component (EPC, eNB, gNB) has its own configuration file.  
These config files are passed as arguments of the run command line, using the option -O \<conf file\>
Remi Hardy's avatar
Remi Hardy committed
82

Remi Hardy's avatar
Remi Hardy committed
83
The **REFERENCE** files for eNB and gNB, **used by the CI**, can be found here:  
84 85
[enb conf file](../ci-scripts/conf_files/enb.band7.tm1.fr1.25PRB.usrpb210.conf)
[gnb conf file](../ci-scripts/conf_files/gnb.band78.tm1.fr1.106PRB.usrpb210.conf)
Remi Hardy's avatar
Remi Hardy committed
86

Remi Hardy's avatar
Remi Hardy committed
87
These files have to be updated manually to set the IP addresses and frequency.  
Remi Hardy's avatar
Remi Hardy committed
88

Remi Hardy's avatar
Remi Hardy committed
89 90 91 92 93

**ATTENTION** : an **EXTERNAL** clock is used to sync the eNB and gNB,  
whether the clock is internal or external is defined in the configuration files (!! details needed !!)   


Remi Hardy's avatar
Remi Hardy committed
94 95 96 97 98 99 100 101 102 103
1- In the **eNB configuration file** :
- look for MME IP address, and update the **ipv4 field** with the IP address of the **EPC** server
```
    ////////// MME parameters:
    mme_ip_address      = ( { ipv4       = "**YOUR_EPC_IP_ADDR**";
                              ipv6       = "192:168:30::17";
                              active     = "yes";
                              preference = "ipv4";
                            }
                          );
Remi Hardy's avatar
Remi Hardy committed
104 105

```
Remi Hardy's avatar
Remi Hardy committed
106 107

- look for S1 IP address, and update the **3 fields below** with the IP address of the **eNB** server  
Remi Hardy's avatar
Remi Hardy committed
108
```
Remi Hardy's avatar
Remi Hardy committed
109 110 111 112 113 114 115 116 117 118
    NETWORK_INTERFACES :
    {
        ENB_INTERFACE_NAME_FOR_S1_MME            = "eth0";
        ENB_IPV4_ADDRESS_FOR_S1_MME              = "**YOUR_ENB_IP_ADDR**";
        ENB_INTERFACE_NAME_FOR_S1U               = "eth0";
        ENB_IPV4_ADDRESS_FOR_S1U                 = "**YOUR_ENB_IP_ADDR**";
        ENB_PORT_FOR_S1U                         = 2152; # Spec 2152
        ENB_IPV4_ADDRESS_FOR_X2C                 = "**YOUR_ENB_IP_ADDR**";
        ENB_PORT_FOR_X2C                         = 36422; # Spec 36422
    };
Remi Hardy's avatar
Remi Hardy committed
119

Remi Hardy's avatar
Remi Hardy committed
120
```
Remi Hardy's avatar
Remi Hardy committed
121

Remi Hardy's avatar
Remi Hardy committed
122 123 124 125 126 127 128 129 130 131 132
2- In the **gNB configuration file** :
- look for MME IP address, and update the **ipv4 field** with the IP address of the **EPC** server
```
    ////////// MME parameters:
    mme_ip_address      = ( { ipv4       = "**YOUR_EPC_IP_ADDR**";
                              ipv6       = "192:168:30::17";
                              active     = "yes";
                              preference = "ipv4";
                            }
                          );
```
Remi Hardy's avatar
Remi Hardy committed
133
- look for X2 IP address, and update the **4 fields** with the IP address of the **eNB** server / **gNB** server as below  (notice : even if -in principle- S1 MME is not required for gNB setting)
Remi Hardy's avatar
Remi Hardy committed
134
```
Remi Hardy's avatar
Remi Hardy committed
135

Remi Hardy's avatar
Remi Hardy committed
136 137 138 139 140 141 142 143 144 145 146 147 148 149 150
    ///X2
    enable_x2 = "yes";
    t_reloc_prep      = 1000;      /* unit: millisecond */
    tx2_reloc_overall = 2000;      /* unit: millisecond */
    target_enb_x2_ip_address      = (
                                     { ipv4       = "**YOUR_ENB_IP_ADDR**";
                                       ipv6       = "192:168:30::17";
                                       preference = "ipv4";
                                     }
                                    );

    NETWORK_INTERFACES :
    {

        GNB_INTERFACE_NAME_FOR_S1_MME            = "eth0";
151
        GNB_IPV4_ADDRESS_FOR_S1_MME              = "**YOUR_GNB_IP_ADDR**";
Remi Hardy's avatar
Remi Hardy committed
152
        GNB_INTERFACE_NAME_FOR_S1U               = "eth0";
153
        GNB_IPV4_ADDRESS_FOR_S1U                 = "**YOUR_GNB_IP_ADDR**";
Remi Hardy's avatar
Remi Hardy committed
154
        GNB_PORT_FOR_S1U                         = 2152; # Spec 2152
155
        GNB_IPV4_ADDRESS_FOR_X2C                 = "**YOUR_GNB_IP_ADDR**";
Remi Hardy's avatar
Remi Hardy committed
156 157 158 159
        GNB_PORT_FOR_X2C                         = 36422; # Spec 36422
    };

    
Remi Hardy's avatar
Remi Hardy committed
160 161 162 163
```



Remi Hardy's avatar
Remi Hardy committed
164
3- The frequency setting requires a manual update in the .C and in the gNB conf file:
Remi Hardy's avatar
Remi Hardy committed
165 166


Remi Hardy's avatar
Remi Hardy committed
167 168 169 170 171 172 173
In the C file **openair2/RRC/LTE/rrc_eNB.c:3217**  
set the nrarfcn to the same value as absoluteFrequencySSB in the **gNB config file**, that is **641272** in the example below 

C file :
```
MeasObj2->measObject.choice.measObjectNR_r15.carrierFreq_r15 =641272;
```
Remi Hardy's avatar
Remi Hardy committed
174

Remi Hardy's avatar
Remi Hardy committed
175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191
gNB config file :

```
    # absoluteFrequencySSB is the central frequency of SSB 
    absoluteFrequencySSB                                          = 641272; 
    dl_frequencyBand                                                 = 78;
    # the carrier frequency is assumed to be in the middle of the carrier, i.e. dl_absoluteFrequencyPointA_kHz + dl_carrierBandwidth*12*SCS_kHz/2
    dl_absoluteFrequencyPointA                                       = 640000;
    #scs-SpecificCarrierList
    dl_offstToCarrier                                              = 0;
    # subcarrierSpacing
    # 0=kHz15, 1=kHz30, 2=kHz60, 3=kHz120  
    dl_subcarrierSpacing                                           = 1;
    dl_carrierBandwidth                                            = 106;
```


Remi Hardy's avatar
Remi Hardy committed
192
## Run and Test
Remi Hardy's avatar
Remi Hardy committed
193

Remi Hardy's avatar
Remi Hardy committed
194 195 196 197
The order to run the different components is important:  
1- first, CN  
2- then, eNB  
3- then, gNB  
Remi Hardy's avatar
Remi Hardy committed
198
4- finally, switch UE from airplane mode ON to OFF (ie Radio from OFF to ON)  
Remi Hardy's avatar
Remi Hardy committed
199 200 201 202 203

It is recommended to redirect the run commands to the same log file (fur further analysis and debug), using ```| tee **YOUR_LOG_FILE**``` especially for eNB and gNB.  
It is not very useful for the CN.  

The test takes typically a few seconds, max 10-15 seconds. If it takes more than 30 seconds, there is a problem. 
Remi Hardy's avatar
Remi Hardy committed
204 205 206 207

- **EPC** (on EPC host):

for reference:
208
https://github.com/OPENAIRINTERFACE/openair-epc-fed/blob/master/docs/DEPLOY_HOME.md
Remi Hardy's avatar
Remi Hardy committed
209 210 211 212 213



- **eNB** (on the eNB host):

Remi Hardy's avatar
Remi Hardy committed
214 215 216 217 218 219 220
Execute: 
```
~/openairinterface5g/cmake_targets/ran_build/build$ sudo ./lte-softmodem -O **YOUR_ENB_CONF_FILE** | tee **YOUR_LOG_FILE**

```


Remi Hardy's avatar
Remi Hardy committed
221
- **gNB** (on the gNB host)
Remi Hardy's avatar
Remi Hardy committed
222

Remi Hardy's avatar
Remi Hardy committed
223

Remi Hardy's avatar
Remi Hardy committed
224 225 226 227
**ATTENTION** : for the gNB execution,    
The **-E** option is required to enable the tri-quarter sampling rate when using a B2xx serie USRP  
The **-E** option is **NOT supported** when using a a N300 USRP  

Remi Hardy's avatar
Remi Hardy committed
228 229
Execute: 
```
Remi Hardy's avatar
Remi Hardy committed
230
~/openairinterface5g/cmake_targets/ran_build/build$ sudo ./nr-softmodem -O **YOUR_GNB_CONF_FILE** -E | tee **YOUR_LOG_FILE**
Remi Hardy's avatar
Remi Hardy committed
231 232 233

```

Remi Hardy's avatar
Remi Hardy committed
234

Remi Hardy's avatar
Remi Hardy committed
235 236
## Test Case

Remi Hardy's avatar
Remi Hardy committed
237 238 239 240 241 242 243 244 245 246
The test case corresponds to the UE attachement, that is the UE connection and its initial access in 5G, as depicted below:

**Source** : https://www.sharetechnote.com/html/5G/5G_LTE_Interworking.html  

![image info](./testing_gnb_w_cots_ue_resources/attach_signaling_scheme.jpg)

The test reaches step **12. E-RAB modifcation confirmation** , eventhough not all the messages will appear in the log file. 

## Log file monitoring

Remi Hardy's avatar
Remi Hardy committed
247 248 249 250
From the log file that is generated, we can monitor several important steps, to assess that the test was successful.  
Log files examples can be found here:  
[enb log file](https://gitlab.eurecom.fr/oai/openairinterface5g/-/blob/rh_doc_update_3/doc/testing_gnb_w_cots_ue_resources/oai_enb.log)  
[gnb log file](https://gitlab.eurecom.fr/oai/openairinterface5g/-/blob/rh_doc_update_3/doc/testing_gnb_w_cots_ue_resources/oai_gnb.log)
Remi Hardy's avatar
Remi Hardy committed
251 252


Remi Hardy's avatar
Remi Hardy committed
253
- eNB receives UE capabilities information, including its NR capabilites, and triggers sGNB Addition Request message:
Remi Hardy's avatar
Remi Hardy committed
254

Remi Hardy's avatar
Remi Hardy committed
255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350
***eNBlog.1315 :***
```
[RRC]   [FRAME 00000][eNB][MOD 00][RNTI 43eb] received ueCapabilityInformation on UL-DCCH 1 from UE
...
[RRC]   [eNB 0] frame 0 subframe 0: UE rnti 43eb switching to NSA mode
...
<X2AP-PDU>
     <initiatingMessage>
         <procedureCode>27</procedureCode>
         <criticality><reject/></criticality>
         <value>
             <SgNBAdditionRequest>
                 <protocolIEs>
                     <SgNBAdditionRequest-IEs>
                         <id>111</id>
<criticality><reject/></criticality>
                         <value>
                             <UE-X2AP-ID>0</UE-X2AP-ID>
                         </value>
                     </SgNBAdditionRequest-IEs>
```

- gNB receives sGNB Addition request, processes UE capabilities for the corresponding UE and triggers sGNB Addition Request ACK, carrying NR RRC Reconfiguration message:


***gNBlog.2291 :***
```
<X2AP-PDU>
     <successfulOutcome>
         <procedureCode>27</procedureCode>
         <criticality><reject/></criticality>
         <value>
             <SgNBAdditionRequestAcknowledge>
                 <protocolIEs>
                     <SgNBAdditionRequestAcknowledge-IEs>
                         <id>111</id>
<criticality><reject/></criticality>
                         <value>
                             <UE-X2AP-ID>0</UE-X2AP-ID>
                         </value>
                     </SgNBAdditionRequestAcknowledge-IEs>
```


- Upon reception of the sGNB Addition Request ACK, the eNB sends a new RRCConnectionReconfiguration message containing the NR Reconfiguration. 
The UE replies with a Reconfiguration Complete message:

***eNBlog.1686 :***
```
[RRC]   [FRAME 00000][eNB][MOD 00][RNTI 43eb] UE State = RRC_RECONFIGURED (default DRB, xid 1)
```

- The Random Access procedure of the UE to the gNB takes place:

***gNBlog.2382 :***
```
[PHY]   [gNB 0][RAPROC] Frame 751, slot 19 Initiating RA procedure with 
preamble 63, energy 35.7 dB, delay 6
 [0m [0m[MAC]   [gNB 0][RAPROC] CC_id 0 Frame 751, Slot 19 Initiating RA 
procedure for preamble index 63
 [0m [0m[MAC]   [gNB 0][RAPROC] CC_id 0 Frame 751 Activating Msg2 
generation in frame 752, slot 7 using RA rnti 10b
 [0m [0m[MAC]   [gNB 0] [RAPROC] CC_id 0 Frame 752, slotP 7: Generating 
RAR DCI, state 1
 [0m [0m[MAC]   [RAPROC] DCI type 1 payload: freq_alloc 120 (0,6,24), 
time_alloc 3, vrb to prb 0, mcs 0 tb_scaling 0
 [0m [0m[MAC]   Frame 752: Subframe 7 : Adding common DL DCI for RA_RNTI 10b
 [0m [0m[MAC]   Frame 752, Subframe 7: Setting Msg3 reception for Frame 
752 Subframe 17
 [0m [0m[PHY]   ULSCH received ok
```

- The eNB triggers the path switch procedure towards the MME, so that 
the traffic can be routed now from the SGW towards the gNB on the S1-U 
plane.

***eNBlog.1691 :***
```
<S1AP-PDU>
     <initiatingMessage>
         <procedureCode>50</procedureCode>
         <criticality><reject/></criticality>
         <value>
             <E-RABModificationIndication>
                 <protocolIEs>
                     <E-RABModificationIndicationIEs>
                         <id>0</id>
<criticality><reject/></criticality>
                         <value>
<MME-UE-S1AP-ID>553648130</MME-UE-S1AP-ID>
                         </value>
                     </E-RABModificationIndicationIEs>
```


Eventually, step **12. E-RAB Modification Confirmation** is successfully reached
Remi Hardy's avatar
Remi Hardy committed
351

Remi Hardy's avatar
Remi Hardy committed
352 353


Remi Hardy's avatar
Remi Hardy committed
354
## Required tools for debug
Remi Hardy's avatar
Remi Hardy committed
355

Remi Hardy's avatar
Remi Hardy committed
356 357 358
- **Wireshark** to trace X2AP and S1AP protocols  
- **Ttracer** for 5G messages  
- **GDB debugger** to check function calls  
Remi Hardy's avatar
Remi Hardy committed
359 360


Remi Hardy's avatar
Remi Hardy committed
361
## Status of interoperability
Remi Hardy's avatar
Remi Hardy committed
362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379

The following parts have been validated with FR1 COTS UE:

- Phone accepts the configurtion provided by OAI eNB:  
    this validates RRC and X2AP  

- Successful Random Access Procedure:  
    PRACH is correctly decoded at gNB  
    Phone correctly receives and decodes msg2 (NR PDCCH Format 1_0 and NR PDSCH)  
    msg3  is transmitted to gNB according to the configuration sent in msg2, and received correctly at gNB    

- Successful path switch of user plane traffic from 4G to 5G cell (E-RAB modification message):  
   this validates S1AP  

- Downlink traffic:  
    PDCCH DCI format 1_1 and correponding PDSCH are decoded correctlyby the phone  
    ACK/NACK (PUCCH format 0) are successfully received at gNB  

Remi Hardy's avatar
Remi Hardy committed
380
- **End-to end UL / DL traffic with HARQ procedures validated (ping, iperf)** 
Remi Hardy's avatar
Remi Hardy committed
381
    
Remi Hardy's avatar
Remi Hardy committed
382 383 384 385
- Known limitations as of September 2020:  
    DL traffic : 3Mbps  
    UL traffic : 1Mbps  
    some packet losses might still occur even in ideal channel conditions  
Remi Hardy's avatar
Remi Hardy committed
386 387


388 389 390 391 392 393 394 395 396 397
## CI integration  
The automation scripts are available on ILIADE.  
The end-to-end test is integrated in the CI flow in a semi-automated manner, comprising 3 steps:  
- update a YAML file comprising the IT resources definition, branch and commit number the test has to run on   
- run the python script that generates the test from the YAML file  
- run the test  

At the date of writing, the test comprises the deployment of the components (epc, eNB, gNB, cots ue) and the execution of 2 pings procedures (20 pings in 20sec, then 5 pings in 1sec)  

This automation is run for every integration branch to be merged into develop.