Out of the Box Test - Command Line Commands

 

The purpose of this tutorial is to give you tips on how to best utilize the command line commands in Amari callbox / UE sim screen to operate the box or analyze / troubleshoot various issues. This tutorial assumes that you are already familiar with the basic operation of the callbox software (e.g, start/restart the service and launching the screen). If you are not familiar with this very basic operation, refer to this tutorial first. You don't have to read and memorize all the commands listed here. Just use this as a cheatsheet and check it out when you are not sure of which command you need to use and what is the syntax of the command.

Command Line Command is at the core of utilizing Amarisoft Product (both eNB/gNB and UEsim) and the more you know of those commands and the better you can use or troubleshoot the product.  So the command line tool would be the first thing you need to learn from Day 1 and the thing you have to live forever with the Amarisoft Product. It may be a little bit intimidating to use the command line tool but we would get used to the power of the command line tool as you play more with it. There are a few categories of the operations you can do with the command line command as listed below.

• Getting the real time status and statistics :  You can get various configuration information and statistics. I think this category is what you get the most familiar with. t , t spl, t cpu, tx_gain, rx_gain, rf_info , cell, cell_phy are the commands that belong to this category. These are the commands that I am personally using everytime when I use Amarisoft product.
• Changing Configuration  :  You can change the configuration while you are running the callbox (eNB/gNB) or UEsim.  Most of the configurations are static and should be configured in *.cfg files for each components but there are some of the commands that can be changed dynamically via command line tool. tx_gain, rx_gain, log are some of the examples in this category. tx_gain, rx_gain would be the commands that you would use most frequently.

You can use the command line commans in a few different ways as listed below.

• In [screen] window :  Probably you would use this way most of the time. run 'screen -x' and run the commands in the screen window as explained in this tutorial .
• Command line tool in WebGUI :  Not so frequently used, but you may want to use this way if you likes to do more in WebGUI without switching back to Screen window. As shown here, you can run a command line window from WebGUI and run all the commands as you do in the [screen] window.

 

Followings is the list of topics to covered in this tutorial. Don't try to memorize everything explained here. Just use this tutorial as a cheatsheet whenver you need to use a specific command and you don't know what to do. Eventually you will reach the point where you don't need this tutorial at all.

 

 

Table of Contents

• Out of the Box Test - Command Line Commands
• Test Setup
• (enb) commands
• help
• t
• t ue
• t cpu
• t g
• cell
• cell phy
• cell main
• ue
• m2
• hwcaps
• s1
• ng
• rf_info
• t spl
• t spl dbm
• rx_gain
• tx_gain
• cell_gain
• handover
• pcap
• (mme) commands
• help
• ue
• ng_ran
• enb
• (UEsim) commands
• help
• t
• cells
• t spl
• t spl dbm
• ue
• t cpu

 

 

Test Setup

 

Test setup for this tutorial is as shown below. (NOTE : Basically it doesn't matter with exact hardware setup to utilize the Command Line Commands. You can use the information in this page for any test setup you are using)

• Since this test is for Out of the box testing, I used the default configuration(cfg) file without changing anything in it
• SIM Card used in this tutorial is the one delivered with the system as it is.
• If you want to change the configuration, The tutorial Information_Config_Guide.pdf would help

 

 

 

(enb) commands

 

In this section, I will show some examples of command line commands used in (enb) mode.

 

help

this command list all the commands you can use and short descriptions about the command.

 

t

't' means 'trace'. it print out logs showing ue and cell information, signal quality, data rate, crc error etc. this is the most commonly used command and you can do a lot of troubleshooting just with this command.

NOTE : For the meaning of each items in this log, refer to this document.

You can use the result of this command and do various troubleshoot as shown below.

 

t ue

this is a variation of 't' command shown above. Unless you specify a specific UE ID, the result of this command would be similar to 't'

: If you specific UE_ID, you can print the log only for the UE that you specified. This can be useful for the case where multiple UEs are connected and you want to print out the log for a specific UE that you are interested.'

 

t cpu

This is a good indicator showing the CPU utilization and real-time processing status. (NOTE : sometimes you would see CPU utilization goes above 100%. Even if it goes over 100%, it is completely normal. It just indicates that more than one CPU is being used. For example, if it is 210%, it mean 3 CPU cores are being used)

NOTE : For further details on interpretation and troubleshoot for this, refer to this wiki.

 

t g

This shows a list of general statistics (global statistics) as shown below. It carries some information like 't' command and some additional information like RRC / UE information.

 

cell

this commands show you the brief information about the cells that are configured.

 

cell phy

This an variation of 'cell' command and it give more of phy related information.

 

cell main

This command shows the cell information about the main cell. If only one cell is configured, this shows the same result as ;cell;

 

ue

This shows the list of UEs that is in communication with eNB/gNB. If UE is not attached or attached but in RRC idle state, you would not see the UE here.

 

m2

 

 

hwcaps

This shows the brief information of hardware capabilities of the call box

 

s1

This command shows that the list of core (mme or amf) that the eNB connected to. In most case you would see only one servers shown here but if you configure the eNB to multiple mme, you will get multiple items as the result of this command.

 

ng

This command shows that the list of core (mme or amf) that the gNB connected to. In most case you would see only one servers shown here but if you configure the gNB to multiple mme, you will get multiple items as the result of this command.

 

rf_info

this command shows you about the information / status of the sdr cards that are being used.

 

t spl

this command shows you the power related information for each and every Tx/Rx port. This is also one of the most frequently used commands. If you see 0 in RX MAX power, it indicates the RX chain is saturated and it may lead to high BLER for the received physical channel. In this case, it is recommended to tweak rx_gain to get the RX MAX to go below 0. (NOTE : The value shown here is dBFS(dB Full Scale), not dBm (absolute power). 0 dBFS indicates the max sample value that the ADC can return)

NOTE : For the meaning of each items in this log, refer to this document.

 

t spl dbm

The role / meaning of this command is exactly same as 't spl' command shown above, the only difference is the unit of the power value. This command shows the power in the unit of dBm. (NOTE : this dbm power is the value converted from dBFS value shown in 't spl', not the value directly measured in dBm).

 

rx_gain

This command is used to view or set rx_gain. this is the most commonly used command for troubleshooting high BLER issues for the received physical channel.

: if you use rx_gain without parameter, it views (prints) the current settings of rx_gain for each RX ports.

: if you use rx_gain with the value, it changes the gains of all RX ports.

If you want to change rx_gain for multiple channels, you can change the gain for all channels simultaneously or separately as shown below.

NOTE : You can set tx gain per each antenna of the cell using tx_gain array and rx_gain array as shown below

For 4 cells with 1 UL antenna and 2 DL antenna as an example

rx_gain : [Cell0Ant1, Cell1Ant1, Cell2Ant1, Cell3Ant1]

tx_gain : [Cell0Ant1, Cell0Ant2, Cell1Ant1, Cell1Ant2, Cell2Ant1, Cell2Ant2, Cell3Ant1, Cell3Ant2]

 

tx_gain

this is used to view or print the gain (tx power) of all the tx ports being used. This would impact decoding performance on UE.  If you see high BLER (high retransmission) for downlink data, usually we try tweaking this value for troubleshoot.

: If you use tx_gain without additional parameter, it prints out the gain of all the TX ports being used.

: if you use tx_gain with the value, it changes the gains of all TX ports.

If you want to change tx_gain for multiple channels, you can change the gain for all channels simultaneously or separately as shown below.

NOTE : In case of configuration file, You can set tx gain per each antenna of the cell using tx_gain array and rx_gain array as shown below

For 4 cells with 1 UL antenna and 2 DL antenna as an example

rx_gain : [Cell0Ant1, Cell1Ant1, Cell2Ant1, Cell3Ant1]

tx_gain : [Cell0Ant1, Cell0Ant2, Cell1Ant1, Cell1Ant2, Cell2Ant1, Cell2Ant2, Cell3Ant1, Cell3Ant2]

 

cell_gain

Change the gain of a specified cell. This is done by callbox software, not by the sdr card.

 

handover

Trigger handover. There should be at least two cells configured and UE should be in connected mode before running this command.

 

pcap

Start Capturing a Pcap file  (NOTE : This is supported only in LTE, not in other radio access technology. We are not extending this function any further because Amarisoft built in log is more powerful and convenient to use)

Stop Capturing

Confirm that the file is properly stored

 

 

 

(mme) commands

 

help

This will give you the list of all the commands and short descriptions that you can use in (mme). (NOTE : The out of help may vary depending on the software version that you are using. So it is recommended to check help and see which commands are supported in your system).

 

ue

: this will give you the list of UEs that are connected to core network. Even when UE gets in Idle mode in RRC, this would still show you the UE that completed the initial attach. This may be the most commonly used command in (mme) because you would want to check the IP assigned to the UE.

 

ng_ran

: this will give you the list of gNB that are connected to core network(AMF).

 

enb

: this will give you the list of eNB that are connected to core network(MME).

 

 

 

(UEsim) commands

 

help

list all the commands available.

 

 

t

prints trace log.

Meaning of each column is described in UEsim doc.

NOTE : RSRP is based on cell specific reference signal power meaning that it is for SSB in NR and PSS/SSS in LTE.  retx, rxko, rxok are based on HARQ Ack/Nack.

NOTE :  It is better to have CFO as low as possible. Typically the ratio of CFO and Subcarrier spacing (i.e, CFO/Subcarrier spacing) is important. In rule of thrumb, less than 2% of the ratio is considered to be a good number.

 

 

cells

list all the configured cells.  If PCI is missing in the print, it mean that the cell is configured but not detected (i.e, not synched)

 

 

t spl

print TX/RX power for each TRX port in dBFS scale.  The important part is RX MAX value. If you see 0 for any of the RX MAX column, it mean that the RX port got saturated. I would suggest you to reduce rx_gain value until you get the value around -5 ~ -10.

NOTE : For the meaning of each items in this log, refer to this document.

NOTE :  Regarding 'SAT' column, some additional description as below would help further.

 The sat column counts the number of times the UE simulator had to limit the TX power of an uplink signal (e.g. PUCCH or PUSCH) so that it does not give a saturated output on the DAC. These saturations do not degrade the signal as the saturation at the sample level (see t spl monitor command) but they indicate that the UE received power at the eNodeB will be lower than expected by the channel simulator.

NOTE :  In most cases you wouldn't see very high TX power or none-zero SAT count, but there would be some cases where you see the cases of too high TX power. there are couple of things you may try to resolve the issue

• enable power_control_enabled
• set  tx_gain_offset

 

 

t spl dbm

print TX/RX power for each TRX port in dbm.

 

 

ue

lists status of every configured UEs.  RRC STATE indicates the status with RAN(i.e, eNB / gNB) and EMM_STATE indicates the status with corenetwork.

 

 

t cpu

This is a good indicator showing the CPU utilization and real-time processing status. (NOTE : sometimes you would see CPU utilization goes above 100%. Even if it goes over 100%, it is completely normal. It just indicates that more than one CPU is being used. For example, if it is 210%, it mean 3 CPU cores are being used)