Tags:
create new tag
, view all tags

How to Connect OAI eNB (USRP B210) with COTS UE

In this tutorial, we will introduce how to connect USRP-B210-based OAI eNB (and OAI EPC) with commercial off-the-shelf (COTS) UE such as smartphones and LTE dongles. We focus on installation and configuration with minimal modifications to sample config files and source codes from OAI. The goal is to help new starters set up the OAI environment as easily and quickly as possible.

The entire procedure is divided into three stages:

  1. Install and configure OAI eNB, EPC and HSS on a single or different hosts. At the end of this stage, EPC should be able to connect to HSS and eNB can connect to EPC + HSS.
  2. Configure UE (e.g., smartphone service mode, USIM card) and register the user on HSS database. At the end of this stage, UE should be able to attach and connect to eNB.
  3. Configure networking settings between eNB and UE. At the end of this stage, they should be able to ping each other and `iperf` can be run to test the throughput.

1. Installation and Configuration of OAI eNB + EPC + HSS

Checklist prior to OAI installation:

  • Ubuntu 14.04 LTS (32-bit or 64-bit)
  • Kernel setup
    • disable C-states from BIOS (or from GRUB)
    • disable CPU freq. scaling
    • install low-latency kernel
  • Install subversion with the command "sudo apt-get install git" (we will be downloading source codes from the trunk at this moment).
Note: If GNURadio has already been installed, check the version of UHD. In most cases, GNURadio downloaded from Ubuntu repositoy is likely to be 3.7.2, which is outdated and does not contain the latest UHD. The OAI build script will try to download UHD 003.008.XXX during automated installation and compilation may fail due to the conflict or missing libraries. So the simplest way is to uninstall GNURadio and outdated UHD libraries.

1.1 Installation

Step 1: Check out the Trunk

First, we will download source codes from the link below as an example.

https://twiki.eurecom.fr/twiki/bin/view/OpenAirInterface/GetSources

We assume that you have following directories

openair-cn : The location of openair-cn git repository

openairinterface5g: The location of openairinterface5g repository.

Step 2: Specify FQDN for EPC

Second, a fully qualified domain name (FQDN) needs to be set for the EPC (MME_GW) [1], before we use the automated script to build eNB, EPC and HSS all at once. An example is as follows. Assume the hostname is "labuser". You may check it in /etc/hostname.

labuser@labuser:$ cat /etc/hostname
labuser

Then fill the FQDN in /etc/hosts as follows:

labuser@labuser:$ cat /etc/hosts
127.0.0.1    localhost
127.0.1.1    labuser.111.111   labuser

"labuser.111.111" is a sample FQDN, where "labuser" is your hostname, and "111.111" is your realm. You can replace "111.111" with other combination.

Step 3: Run Automated Build Script (openairinterface5g)

Next, we will use the automated build script ~/trunk/cmake_targets/build_oai to build OAI eNB, EPC (i.e., MME_GW) and HSS on a single/local host.

cd ~/openairinterface
source oaienv
cd cmake_targets
./build_oai -I -g --eNB -x --install-system-files -w USRP  --install-optional-packages

You can print out the help message to see what these options mean using the command "./build_oai -h". A short summary is as follows.

  • -I: installs required packages.
  • -g: adds debugging symbols to compilation directives.
  • --eNB: installs eNB, i.e., lte-softmodem.
  • -x: adds a software oscilloscope feature to the produced binaries.
  • --install-system-files: installs OAI required files in Linux system.
  • -w: adds the hardware support, which is USRP in our case.
  • --install-optional-packages: Installs optional packages
During the building process, you will be asked to set the password for MySQL "root" user. You are recommended to use "linux", since this is the default password used by OAI; otherwise, you will have to edit some configuration file so that HSS is able to access MySQL database.
 __Notes:__ 
  • If you have previously build OAI on your host, please use -c or -C to remove existing compiled files.
  • If you want to host eNB, EPC and HSS separately, the same process applies but configurations are different as will be mentioned later.
Look at https://twiki.eurecom.fr/twiki/bin/view/OpenAirInterface/AutoBuild for more details

Step 4: Run Automated script for openair-cn

./build_epc -i (Need to run only once to install missing packages)

./build_hss -i (Need to run only once to install missing packages)

The detailed instructions for EPC are located in: YOUR_openair-cn_DIRECTORY/DOCS/EPC_User_Guide.pdf

Look at https://twiki.eurecom.fr/twiki/bin/view/OpenAirInterface/AutoBuild for more details

1.2 Configuration

1.2.1 eNB and EPC+HSS on a Single/Local host

figure_local_eNB_EPC.png

Figure 1. eNB, EPC (MME+S/PGW) and HSS on a single/local host [1].

The corresponding configurations are as follows (you don't need to change the sample configuration files a lot).

In eNB configuration file (~/openairinterface5g/targets/PROJECT/GENERIC-LTE-EPC/CONF/enb.band7.tm1.usrpb210.epc.local.conf:

... preference="ipv4";});

// Tracking area code, 0x0000 and 0xfffe are reserved values

tracking_area_code = "1";

mobile_country_code = "208";

mobile_network_code = "95";

////////// Physical parameters:

...

////////// MME parameters:

mme_ip_address = ( {ipv4 = "192.170.0.1";

ipv6="192:168:30::17";

active="yes";

NETWORK_INTERFACES :

{

ENB_INTERFACE_NAME_FOR_S1_MME = "eth0:3";

ENB_IPV4_ADDRESS_FOR_S1_MME = "192.170.0.2/24";

ENB_INTERFACE_NAME_FOR_S1U = "eth0:4";

ENB_IPV4_ADDRESS_FOR_S1U = "192.170.1.2/24";

ENB_PORT_FOR_S1U = 2152; # Spec 2152

};

In EPC configuration file (~/openair-cn/BUILD/EPC/epc.conf.in):

...

# ------- MME served GUMMEI
GUMMEI :
{
# MME code DEFAULT = 0
# size = 8 bits
# maximum of 256 values, comma separated
MME_CODE = [ 1, 30 , 31, 32, 33, 34, 35, 36, 56 , 29 , 8 ];

# MME GROUP ID DEFAULT = 0
# size = 16 bits
# maximum of 65535 values, comma separated
MME_GID = [ 32768 , 4 , 5 , 30 , 8 , 9 , 50021 ];

# TA (mcc.mnc:tracking area code) DEFAULT = 208.34:0
# max values = 999.999:65535
# maximum of 32 values, comma separated
TAI_LIST = (
{MCC="208" ; MNC="95"; TAC = "1"; } # YOUR PLMN CONFIG HERE
);
};

NAS :
{
# 3GPP TS 33.401 section 7.2.4.3 Procedures for NAS algorithm selection
# decreasing preference goes from left to right
ORDERED_SUPPORTED_INTEGRITY_ALGORITHM_LIST = [ "EIA2" , "EIA1" , "EIA0" ];
ORDERED_SUPPORTED_CIPHERING_ALGORITHM_LIST = [ "EEA0" , "EEA1" , "EEA2" ];
};

NETWORK_INTERFACES :
{
MME_INTERFACE_NAME_FOR_S1_MME = "eth0:1"; # YOUR NETWORK CONFIG HERE
MME_IPV4_ADDRESS_FOR_S1_MME = "192.170.0.1/24"; # YOUR NETWORK CONFIG HERE

MME_INTERFACE_NAME_FOR_S11_MME = "none";
MME_IPV4_ADDRESS_FOR_S11_MME = "0.0.0.0/24";
};
};

S-GW :
{
NETWORK_INTERFACES :
{
SGW_INTERFACE_NAME_FOR_S11 = "none";
SGW_IPV4_ADDRESS_FOR_S11 = "0.0.0.0/24";

SGW_INTERFACE_NAME_FOR_S1U_S12_S4_UP = "eth0:2"; # YOUR NETWORK CONFIG HERE
SGW_IPV4_ADDRESS_FOR_S1U_S12_S4_UP = "192.170.1.1/24"; # YOUR NETWORK CONFIG HERE
SGW_IPV4_PORT_FOR_S1U_S12_S4_UP = 2152; # PREFER NOT CHANGE

SGW_INTERFACE_NAME_FOR_S5_S8_UP = "none"; # DO NOT CHANGE
SGW_IPV4_ADDRESS_FOR_S5_S8_UP = "0.0.0.0/24"; # DO NOT CHANGE
};
};

P-GW =
{
NETWORK_INTERFACES :
{
PGW_INTERFACE_NAME_FOR_S5_S8 = "none"; # DO NOT CHANGE
PGW_IPV4_ADDRESS_FOR_S5_S8 = "0.0.0.0/24"; # DO NOT CHANGE

PGW_INTERFACE_NAME_FOR_SGI = "eth0"; # YOUR NETWORK CONFIG HERE
PGW_IPV4_ADDRESS_FOR_SGI = "192.168.12.213/24"; # YOUR NETWORK CONFIG HERE
PGW_MASQUERADE_SGI = "yes"; # YOUR NETWORK CONFIG HERE
};

IP_ADDRESS_POOL :
{
IPV4_LIST = (
"192.188.0.0/24", # YOUR NETWORK CONFIG HERE
"192.188.1.0/24" # YOUR NETWORK CONFIG HERE
);
IPV6_LIST = (
"2014:02:26::0/120" # YOUR NETWORK CONFIG HERE
);
};

DEFAULT_DNS_IPV4_ADDRESS = "192.168.106.12"; # YOUR NETWORK CONFIG HERE
DEFAULT_DNS_SEC_IPV4_ADDRESS = "192.168.12.100"; # YOUR NETWORK CONFIG HERE
};

Note that PGW_IPV4_ADDRESS_FOR_SGI is the address used by EPC to access the (external) Internet.

1.2.2 eNB and EPC+HSS on Different Hosts

Next, we explain the setup for running eNB and EPC+HSS on two different hosts. Assume the IP addresses of eNB and EPC+HSS are 192.168.100.102 and 192.168.100.103. Figure 2 is an example which specifies the network topology.

eNB_EPC_different_hosts.png

Figure 2. eNB, EPC (MME+S/PGW) and HSS on different hosts.

Then, make sure the networking parameters are properly specified in eNB and EPC configuraiton files. In eNB configuration file (~/openairinterface5g/targets/PROJECT/GENERIC-LTE-EPC/CONF/enb.band7.tm1.usrpb210.epc.remote.conf),


tracking_area_code  =  "1";
mobile_country_code =  "208";
mobile_network_code =  "93";


////////// MME parameters:
    mme_ip_address      = ( { ipv4       = "192.168.100.103";
                              ipv6       = "192:168:30::17";
                              active     = "yes";
                              preference = "ipv4";
                            }
                          );
    NETWORK_INTERFACES :
    {
        ENB_INTERFACE_NAME_FOR_S1_MME         = "eth1";
        ENB_IPV4_ADDRESS_FOR_S1_MME           = "192.168.100.102/24";

        ENB_INTERFACE_NAME_FOR_S1U            = "eth1";
        ENB_IPV4_ADDRESS_FOR_S1U              = "192.168.100.102/24";
        ENB_PORT_FOR_S1U                      = 2152; # Spec 2152
    };

where mme_ip_address is network interface's IP address of your EPC/HSS, and NETWORK_INTERFACE is your eNB related network interface information.

In EPC configuration file (~/openair-cn/BUILD/EPC/epc.conf.in):


TAI_LIST = (
{MCC="208" ; MNC="93";  TAC = "1"; }                              # YOUR PLMN CONFIG HERE</div>
);


NETWORK_INTERFACES :
    {
        MME_INTERFACE_NAME_FOR_S1_MME         = "eth1";
        MME_IPV4_ADDRESS_FOR_S1_MME           = "192.168.100.103/24";

        MME_INTERFACE_NAME_FOR_S11_MME        = "none";
        MME_IPV4_ADDRESS_FOR_S11_MME          = "0.0.0.0/24";
    };
S-GW :
{
    NETWORK_INTERFACES :
    {
        SGW_INTERFACE_NAME_FOR_S11            = "none";
        SGW_IPV4_ADDRESS_FOR_S11              = "0.0.0.0/24";

        SGW_INTERFACE_NAME_FOR_S1U_S12_S4_UP  = "eth1";
        SGW_IPV4_ADDRESS_FOR_S1U_S12_S4_UP    = "192.168.100.103/24";          
        SGW_IPV4_PORT_FOR_S1U_S12_S4_UP       = 2152;
        
        SGW_INTERFACE_NAME_FOR_S5_S8_UP       = "none";
        SGW_IPV4_ADDRESS_FOR_S5_S8_UP         = "0.0.0.0/24";
    };
};
P-GW :
{
    NETWORK_INTERFACES : 
    { 
        PGW_INTERFACE_NAME_FOR_S5_S8          = "none";
        PGW_IPV4_ADDRESS_FOR_S5_S8            = "0.0.0.0/24";

        PGW_INTERFACE_NAME_FOR_SGI            = "eth1";
        PGW_IPV4_ADDRESS_FOR_SGI              = "192.168.100.103/24";
        PGW_MASQUERADE_SGI                    = "yes";
     };
     ...
}

Note that PGW_IPV4_ADDRESS_FOR_SGI is the address used by EPC to access the (external) Internet.

Acknowledge: this example was provided by Yeoh Chun-Yeow in one previous email.

1.3.1 Running eNB, EPC and HSS (Assuming eNB, EPC, HSS are on same machine)

Compile & Run EPC:

cd ~/openair-cn

cd SCRIPTS

./build_epc -c -l

./run_epc -i -r

Compile & Run HSS:

cd ~/openair-cn

cd SCRIPTS

./build_hss -c -l

./run_hss

After EPC is connected to HSS (you should see both enter STATE_OPEN from the terminal), compile and start eNB with the following commands below:

Compile & Run eNB:

cd ~/openairinterface5g

source oaienv

./cmake_targets/build_oai -w USRP -x -c --eNB

cd cmake_targets/lte_build_oai/build

sudo ifconfig eth0:3 192.170.0.2 up

sudo ifconfig eth0:4 192.170.1.2 up

sudo -E ./lte-softmodem -O $OPENAIR_DIR/targets/PROJECT/GENERIC-LTE-EPC/CONF/enb.band7.tm1.usrpb210.epc.local.conf -d

sudo -E ./lte-softmodem -h (to see help options)

You may print out the help message to see other options. A summary of the above options is given below.

  • -O: configuration file
  • -m: set the maximum downluink MCS
  • -t: set the maximum uplink MCS
  • -x: set the transmission mode, valid option: 1
  • -W: enable L2 Wireshark messages on localhost
Note: some other options are very useful for debugging purposes, such as -V, which enables VCD and generates a log file (/tnp/openair_dump_eNB.vcd) with a lot of details, and -d, which enables software oscilloscope with interactive graphic interfaces. Since both consume a lot of computing resources (one is heavy on file access, the other one is heavy on graphics), you are recommended to disable them for normal use.

If the first run is not successful and you are recommended to lower RX gain by some value, change rx_gain to a lower value in eNB configuration file. When eNB is successfully connected, you should see something like the following on eNB terminal:

... 
[SCHED][eNB] Started eNB main thread on CPU 1 TID 5273
eNB_thread: mlockall in ...
eNB_thread: mlockall out ...
waiting for sync (eNB_thread)
TYPE <CTRL-C> TO TERMINATE
Entering ITTI signals handler

1.3.2 Running eNB, EPC and HSS (Assuming eNB, {EPC, HSS} are on different machines)

Compile & Run EPC:

cd ~/openair-cn

cd SCRIPTS

./build_epc -c -l

./run_epc -r

Compile & Run HSS:

cd ~/openair-cn

cd SCRIPTS

./build_hss -c -l

./run_hss

After EPC is connected to HSS (you should see both enter STATE_OPEN from the terminal), compile and start eNB with the following commands below:

Compile & Run eNB:

cd ~/openairinterface5g

source oaienv

./cmake_targets/build_oai -w USRP -x -c --eNB

cd cmake_targets/lte_build_oai/build

sudo -E ./lte-softmodem -O $OPENAIR_DIR/targets/PROJECT/GENERIC-LTE-EPC/CONF/enb.band7.tm1.usrpb210.epc.remote.conf -d


1.4 Possible Issues

Issue 1: EPC Fails to Connect to HSS (1)

If you miss Step 2 in Section 1.1, your EPC may fail to connect to HSS. Check the following configurations. Assume your hostname is "labuser" (/etc/hostname) and your FQDN is "labuser.111.111" in /etc/hosts (see tutorial for this part). Then in EPC configuration file,

REALM = "111.111"
HSS_HOSTNAME = "labuser"

In /usr/etc/freeDiameter/hss_fd.conf:

Identity="labuser.111.111"
Realm="111.111"
ConnectPeer = "labuser.111.111" {ConnectTo = "127.0.1.1"; Realm="111.111"; No_IPv6; No_TLS; port = 3870;}

In /usr/etc/freeDiameter/mme_fd.conf:

Identity="labuser.111.111"
Realm="111.111"

If this is the issue, the easiest way is to specify FQDN and rebuild EPC using the "build_oai" script in ~/openairinterface5g/cmake_targets with the -C or -c option (which removes all previously compilations):

./build_oai -c --eNB  -w USRP

Issue 2: EPC Fails to Connect to HSS (2)

Another possible cause is that mobile country code (MCC), mobile network code (MNC) and tracking area code (TAC) are not matched in configuration files for eNB and EPC. You need to make sure they match if you want to use your own.

2. UE Configuration and User Registration on HSS Database

Now eNB, EPC and HSS are working properly, and we may move to the next stage. Assume that the UE or USIM card has the following information (Link):

  • MCC (Mobile Country Code): 208
  • MNC (Mobile Network Code): 93
  • TAC (Tracking Area Code): 123
  • IMSI: 208930000000001
  • Ki: 8BAF473F2F8FD09487CCCBD7097C6862 (32 digits)
  • OP (Operator Key): 11111111111111111111111111111111 (32 digits)
You may other combinations as you like.

2.1 USIM Card Programming

TBD (description USIM programming device + procedure + pics)

2.2 UE Configuration

TBD (pics + description)

2.2.1 Smartphone: Samsung S3

2.2.2 Smartphone: Samsung S4 mini

You have to create a new APN profile in your smartphone according the one that you will assign to the UE in the HSS database. So you have to go Settings->Mobile network settings->Access Point Names-> Add a new apn.

Give a name to this apn profile (e.g. eur). At the APN field write the name that exists on the HSS database (e.g. oai.ipv4). At the Bearer field check the option LTE.

Save the apn profile and then select it.

2.2.3 LTE Dongle: Bandrich LTE Dongle C501

2.2.4 LTE Dongle: Huawei E3372

For this LTE Dongle you don't have to give at commands in order to configure it but you can do it from the graphical interface that it is on the url 192.168.8.1. You have to go to Profile Management and add a new APN profile (see the picture below)

huawei_apn.png

2.3 User Registration on HSS Database

In order for UE to complete the attach procedure successfully, we need to register the user on HSS database.

Step 1: Install Phpmyadmin (Optional)

In this case, phpmyadmin may come handy to you. Alternatively, you may access MySQL database from the command line. The instructions are available here. In most cases, the following commands will work for you.

sudo apt-get install phpmyadmin
sudo ln -s /etc/phpmyadmin/apache.conf /etc/apache2/conf-available/phpmyadmin.conf
sudo a2enconf phpmyadmin
sudo /etc/init.d/apache2 reload

Then you can access the HSS database via http://127.0.0.1/phpmyadmin/ with username "hssadmin" and password "admin".

Step 2: Add User to Table oai_db.users

You may check out existing users in the database via phpmyadmin. However, you may not be able to insert a user record on phpmyadmin, because the Key (as well as OPc) is stored as binary in the database. Use the following commands as a guide.

shell > mysql -u root -p
# The password is "linux"
mysql > use oai_db;
mysql > INSERT INTO users (`imsi`, `msisdn`, `imei`, `imei_sv`, `ms_ps_status`, `rau_tau_timer`, 
     -> `ue_ambr_ul`, `ue_ambr_dl`, `access_restriction`, `mme_cap`, `mmeidentity_idmmeidentity`, 
     -> `key`, `RFSP-Index`, `urrp_mme`, `sqn`, `rand`, `OPc`) 
     -> VALUES ('208930000000001',  '33638060010', NULL, NULL, 'PURGED', '120', '50000000', '100000000', 
     -> '47', '0000000000', '3', 0x8BAF473F2F8FD09487CCCBD7097C6862, '1', '0', '', 
     -> 0x00000000000000000000000000000000, '');

There are a couple of things to note:

  • msisdn: even though it is optional, you may not leave it blank since OAI will check its presence (any value would be fine).
  • OPc: OPc is computed from OP and Key. You may leave it NULL, since HSS will compute it for you; or you may use the online tools listed here to compute the value.
  • mmeidentity_idmmeidentity: the value is 3 here; it has to match the one in Table oai_db.mmeidentity.

Step 3: Update Tables oai_db.mmeidentity and oai_db.pdn

You can directly insert a record to oai_db.mmeidentity via phpmyadmin. In this case, "idmmeidentity" is 3, "mmehost" is "labuser.111.111" and "mmerealm" is "111.111".

Also, you need to insert a record to oai_db.pdn for the user via phpmyadmin.

2.4 Connect UE to eNB

2.5 Possible Issues

Issue 1: MNC Not Found (mcc_mnc_list)

If you choose a good combination of MCC and MNC that is not currently in the mcc_mnc_list, you may see some error like the following on the EPC terminal:

...
Assertion (0) failed!
In mme_app_handle_nas_auth_param_req() /home/labuser/trunk/openair-cn/MME_APP/mme_app_authentication.c:291
MNC Not found (mcc_mnc_list)
...

So the solution is to add your own combination to the mcc_mnc_list located in ~/trunk/openair-cn/UTILS/mcc_mnc_itu.c. Then you can rebuild EPC with the following command.

~/openair-cn/SCRIPTS/build_epc (Run this command with options as discussed in sections above)

Issue 2: iptables: No chain/target/match by that name.

...
iptables: No chain/target/match by that name.
[SPGW-APP][E]ERROR in system command iptables -t mangle -A FORWARD -d 192.168.3.2 -m mark --mark 0 
-j GTPUSP --own-ip 127.0.0.1 --own-tun 1 --peer-ip 127.0.0.1 --peer-tun 3396329693 --action add: 256 
at /home/labuser/trunk/openair-cn/SGW-LITE/sgw_lite_handlers.c:897

If you see an error like this, insert ~/trunk/targets/bin/xt_GTPUSP.ko:

sudo insmod ~/trunk/targets/bin/xt_GTPUSP.ko

3. Networking Configuration for UE and eNB

References:

[1] EPC_User_Guide.pdf

-- XuhangYing, VirgiliosPassas - 25 Jul 2015

Topic attachments
I Attachment Action Size Date Who Comment
PNGpng eNB_EPCHSS_local_host.png manage 106.8 K 02 Aug 2015 - 02:37 XuhangYing eNB and EPC+HSS on a single/local host
PNGpng eNB_EPC_different_hosts.png manage 112.9 K 02 Aug 2015 - 02:08 XuhangYing eNB and EPC+HSS at different hosts
Unknown file formatconf enb.band7.tm1.usrpb210.epc.local.conf manage 6.8 K 14 Jan 2016 - 12:17 LionelGauthier eNB config file when eNB/EPC are on same machines
Unknown file formatin epc.conf.in manage 8.1 K 14 Jan 2016 - 12:16 LionelGauthier EPC config file
PNGpng epc.png manage 87.0 K 27 Jul 2015 - 01:39 XuhangYing EPC
PNGpng epc_commented.png manage 143.2 K 27 Jul 2015 - 02:02 XuhangYing eNB + EPC + HSS on a local hsot
PNGpng figure_local_eNB_EPC.png manage 12.1 K 14 Jan 2016 - 11:36 LionelGauthier  
PNGpng huawei_apn.png manage 189.4 K 06 Aug 2015 - 12:11 VirgiliosPassas Add APN profile to LTE Dongle Huawei 3372
Topic revision: r14 - 20 Jan 2016 - RohitGupta
 
Copyright 2004-2010 Institut Eurecom & all contributing authors.