TESTING_GNB_W_COTS_UE.md 14.2 KB
Newer Older
Remi Hardy's avatar
Remi Hardy committed
1
STATUS 2020/10/15 : added External Resources section and links  
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
## Table of Contents ##

Remi Hardy's avatar
Remi Hardy committed
6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28
1.   [External Resources](#external-resources) 
2.   [Configuration Overview](#configuration-overview)
3.   [SW Repository / Branch](#repository)
4.   [Architecture Setup](#architecture-setup)
5.   [Build / Install](#build-and-install)
6.   [Run / Test](#run-and-test)
7.   [Test case](#test-case)
8.   [Log file monitoring](#log-file-monitoring)
9.   [Required tools for debug](#required-tools-for-debug)
10.   [Status of interoperability](#status-of-interoperability) 
11.   [CI integration](#ci-integration)  


## External Resources

Additional Resources to this page can be found here (special mention to Walter Maguire <wmaguire@live.com>) :  
https://docs.google.com/document/d/1pL8Szm0ocGxdl5ESVp12Ff71a4PbhCb9SpvbLZzwYbo/edit?usp=sharing  
At time of writing, the openairinterface5G Commit Tag is 2020.w39


Faraday Cages can be found here :  
http://www.saelig.com/MFR00066/ste2300.htm

Remi Hardy's avatar
Remi Hardy committed
29 30

## Configuration Overview
Remi Hardy's avatar
Remi Hardy committed
31 32 33 34 35 36

* 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
37
* 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
38 39 40 41 42
* 5G TDD duplexing mode
* 5G FR1 Band n78 (3.5 GHz)
* BW: 40MHz
* Antenna scheme: SISO

Remi Hardy's avatar
Remi Hardy committed
43
## Repository
Remi Hardy's avatar
Remi Hardy committed
44 45 46 47 48

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

## Architecture Setup

Remi Hardy's avatar
Remi Hardy committed
49
The scheme below depicts our typical setup:
Remi Hardy's avatar
Remi Hardy committed
50

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

Remi Hardy's avatar
Remi Hardy committed
53 54 55
The photo depicts the FR1 setup part of the scheme above:  


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

Remi Hardy's avatar
Remi Hardy committed
58
## Build and Install
Remi Hardy's avatar
Remi Hardy committed
59

Remi Hardy's avatar
Remi Hardy committed
60
General guidelines to build eNB and gNB :
Remi Hardy's avatar
Remi Hardy committed
61 62 63
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
64
- **eNB**
Remi Hardy's avatar
Remi Hardy committed
65 66

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

Remi Hardy's avatar
Remi Hardy committed
72 73
```

Remi Hardy's avatar
Remi Hardy committed
74
- **gNB**
Remi Hardy's avatar
Remi Hardy committed
75 76

```
Remi Hardy's avatar
Remi Hardy committed
77 78 79 80
cd <your oai installation directory>/openairinterface5g/
source oaienv
cd cmake_targets/
./build_oai -I -w USRP --gNB
Remi Hardy's avatar
Remi Hardy committed
81 82
```

Remi Hardy's avatar
Remi Hardy committed
83 84 85 86

- **EPC**

for reference:
hardy's avatar
hardy committed
87
https://github.com/OPENAIRINTERFACE/openair-epc-fed/blob/master/docs/DEPLOY_HOME.md
Remi Hardy's avatar
Remi Hardy committed
88 89 90



Remi Hardy's avatar
Remi Hardy committed
91
## Configuration Files
Remi Hardy's avatar
Remi Hardy committed
92

Remi Hardy's avatar
Remi Hardy committed
93 94
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
95

Remi Hardy's avatar
Remi Hardy committed
96
The **REFERENCE** files for eNB and gNB, **used by the CI**, can be found here:  
97 98
[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
99

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

Remi Hardy's avatar
Remi Hardy committed
102 103 104 105 106

**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
107 108 109 110 111 112 113 114 115 116
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
117 118

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

- 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
121
```
Remi Hardy's avatar
Remi Hardy committed
122 123 124 125 126 127 128 129 130 131
    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
132

Remi Hardy's avatar
Remi Hardy committed
133
```
Remi Hardy's avatar
Remi Hardy committed
134

Remi Hardy's avatar
Remi Hardy committed
135 136 137 138 139 140 141 142 143 144 145
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
146
- 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
147
```
Remi Hardy's avatar
Remi Hardy committed
148

Remi Hardy's avatar
Remi Hardy committed
149 150 151 152 153 154 155 156 157 158 159 160 161 162 163
    ///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";
164
        GNB_IPV4_ADDRESS_FOR_S1_MME              = "**YOUR_GNB_IP_ADDR**";
Remi Hardy's avatar
Remi Hardy committed
165
        GNB_INTERFACE_NAME_FOR_S1U               = "eth0";
166
        GNB_IPV4_ADDRESS_FOR_S1U                 = "**YOUR_GNB_IP_ADDR**";
Remi Hardy's avatar
Remi Hardy committed
167
        GNB_PORT_FOR_S1U                         = 2152; # Spec 2152
168
        GNB_IPV4_ADDRESS_FOR_X2C                 = "**YOUR_GNB_IP_ADDR**";
Remi Hardy's avatar
Remi Hardy committed
169 170 171 172
        GNB_PORT_FOR_X2C                         = 36422; # Spec 36422
    };

    
Remi Hardy's avatar
Remi Hardy committed
173 174 175 176
```



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


Remi Hardy's avatar
Remi Hardy committed
180 181 182 183 184 185 186
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
187

Remi Hardy's avatar
Remi Hardy committed
188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204
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
205
## Run and Test
Remi Hardy's avatar
Remi Hardy committed
206

Remi Hardy's avatar
Remi Hardy committed
207 208 209 210
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
211
4- finally, switch UE from airplane mode ON to OFF (ie Radio from OFF to ON)  
Remi Hardy's avatar
Remi Hardy committed
212 213 214 215 216

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
217 218 219 220

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

for reference:
221
https://github.com/OPENAIRINTERFACE/openair-epc-fed/blob/master/docs/DEPLOY_HOME.md
Remi Hardy's avatar
Remi Hardy committed
222 223 224 225 226



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

Remi Hardy's avatar
Remi Hardy committed
227 228 229 230 231 232 233
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
234
- **gNB** (on the gNB host)
Remi Hardy's avatar
Remi Hardy committed
235

Remi Hardy's avatar
Remi Hardy committed
236

Remi Hardy's avatar
Remi Hardy committed
237 238 239 240
**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
241 242
Execute: 
```
Remi Hardy's avatar
Remi Hardy committed
243
~/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
244 245 246

```

Remi Hardy's avatar
Remi Hardy committed
247

Remi Hardy's avatar
Remi Hardy committed
248 249
## Test Case

Remi Hardy's avatar
Remi Hardy committed
250 251 252 253 254 255 256 257 258 259
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
260 261 262 263
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
264 265


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

Remi Hardy's avatar
Remi Hardy committed
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 351 352 353 354 355 356 357 358 359 360 361 362 363
***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
364

Remi Hardy's avatar
Remi Hardy committed
365 366


Remi Hardy's avatar
Remi Hardy committed
367
## Required tools for debug
Remi Hardy's avatar
Remi Hardy committed
368

Remi Hardy's avatar
Remi Hardy committed
369 370 371
- **Wireshark** to trace X2AP and S1AP protocols  
- **Ttracer** for 5G messages  
- **GDB debugger** to check function calls  
Remi Hardy's avatar
Remi Hardy committed
372 373


Remi Hardy's avatar
Remi Hardy committed
374
## Status of interoperability
Remi Hardy's avatar
Remi Hardy committed
375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392

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
393
- **End-to end UL / DL traffic with HARQ procedures validated (ping, iperf)** 
Remi Hardy's avatar
Remi Hardy committed
394
    
Remi Hardy's avatar
Remi Hardy committed
395 396 397 398
- 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
399 400


401 402 403 404 405
## 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  
406 407 408 409
```
python3 obj_build_from_yaml.py py_params_template.yaml fr1.sh
```
- run the test (fr1.sh)
410 411 412 413

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.