Remote API

 

The purpose of this tutorial is to show you how to do use RemoteAPI. Remote API is a tool to let you communicate with Callbox using WebSocket protocol and any programming lanaguage supporting WebSocket. In Amaricall box, you will have a special script installed by default for RemoteAPI utilization.

Most of the test equipment support their own automation / remote control mechanism and the most commonly used mechanism would be GPIB/SCPI (skippy). Amarisoft also provides its own automation / remote control mechanism, but it is not based on SCPI. Instead Amarisoft product provides a special automation/remote controll tool named 'Remote API'. The Remote API is based on Java Script utilizing Web Socket to control/communicate with Amari Callbox or UEsim. The command format is in json format.

Remote API would seem a little bit complicated and confusing at the beginning if you are just familiar with SCPI type of command, but you would relize that Remote API would provide wider range of controllability than most of the SCPI style command set. I would strongly suggest you to try Remote API and try to get familiar with the tool.

NOTE :  Remote API in  Python, we not providing Python based remote API in standard release package, but you may use the sample Python code in this tutorial. You may use it as it is or modify as you like.

 

 

Table of Contents

• Remote API
• Test Setup
• Check if nodeJ is installed
• What if nodeJ is not installed
• Finding ws.js
• Checking ws.js
• How to figure out IP and Port number for Callbox (or UEsim) component ?
• enb Remote API
• enb Remote API for cell specific configurations
• mme Remote API
• UEsim Remote API
• Application Examples
• Troubleshooting Tips
• Syntax Error : Unexpected Token
• JSON String issue on Windows 

 

 

Test Setup

 

You can use any kind of test setup that allow you to get UE attached to callbox.

 

 

Check if nodeJ is installed

 

Remote API is based on standard WebSocket protocol, so you can use any language (e.g, Python, Perl etc) to utilize this functionality, but Java script is the most widely tested by Amarisoft for this purpose

To use RemoteAPI with javascript, we need to install a javascript package called NodeJ. In recent callbox (I used 2021-11-19 release), it seems the NodeJ is installed by default. The objective of this section is to check if the nodeJ is installed and functioning properly

 

Try the command : { node -v }. If you get any result (i.e, version number) printed out, it mean that NodeJ is already installed on the PC

As a quick test, run { node } command and you will get node program prompt (NOTE : This is just to check if node is propery working. This is NOT the way you run RemoteAPI. For running RemoteAPI, refer the section Checking ws,js and try with some of the basic examples in this tutorial).

You may define a simple HelloWorld() function and call it and check if it works OK.

Press Ctrl+D to get out of node program

 

 

What if nodeJ is not installed

 

If nodeJ package is not installed on the PC (callbox), you can install it with following commands. In this case, you need to get your PC connected to the internet

 

 

 

Finding ws.js

 

The location of ws.js is a little bit different depending on release of the installlation package.

If you are using a little bit older versions, you may find it at  /root/mme/doc as shown below.

But in recent relase, the location of ws has changed. If you don't find the ws.js in /root/mme/doc, you can check out /root/enb, /root/mme, /root/ots  or you can search the location of the ws.js file using 'find' command as shown below.

 

 

 

Checking ws.js

The simplest way to check if the remoteAPI is properly running is to send a simple command and see if you get the proper response as shown below. For this specific test, you just need to make it sure that lte service but you don't need to get any UE attached.

 

 

How to figure out IP and Port number for Callbox (or UEsim) component ?

 

It would be easier to use component name in the remote API command, but if you want to use the IP and port number and you don't know the specific IP:port number for the component that you want to communicate. You can easily fiture it out from ws.js file. Open up ws.js in a text editor and you can figure it out as below.

 

NOTE : The IP address and Port Number shown above is based on the default value of com_addr parameter as shown below in each cfg file (e.g, enb.cfg, mme.cfg etc). If you change this parameter, you have to use the explicit IP and port number when you send RemoteAPI command.

 

 

enb Remote API

 

A challenge to use Remote API is that it is difficult to figure out accurate syntax of the each API just from the document. Main objective of this tutorial is to make a list of examples that is tested working. You may just copy and past of these examples for your needs but be careful about the parameter value and change those values as per the call status which your DUT is in (e.g, UE ID). This list will keep updated as I try more. So refer to the latest version of this tutorial to get more examples.

NOTE :  Refer to lteenb.pdf -  10. Remote API for the official description of the eNB/gNB related Remote API Command

NOTE :  In the examples shown below, I used 'enb' instead of the specific IP. This would work if you are running these commands on Callbox PC without changing com_addr parameter in the configuration file. But if you have changed com_addr parameter in the configuration file or if you are running the RemoteAPI from other PC, you need to put a specific < IP:port > in the place of 'end' in the following examples (e.g, ./ws.js 192.168.1.15:9000 '{"message":"config_get"}')  

NOTE : some number shown in this example (e.g, enb_ue_id) is context dependant meaning it should be changed according to the call status in the call box as of testing. Otherwise, the command would not work and may generate errors

NOTE :  For Windows users, you may get errors if you just copy and paste the command as below. Check out JSON String issue on Windows to workaround the problem.

./ws.js enb '{"message":"config_get"}'  

./ws.js enb '{"message":"config_set","logs":{"bcch":false}}'

./ws.js enb '{"message":"config_set","logs":{"layers":{"PHY":{"level":"debug","max_size":1,"payload":true}},"bcch":false}}'

./ws.js enb '{"message":"stats"}'

./ws.js enb '{"message":"stats", "samples":true}'

./ws.js enb '{"message":"stats", "samples":true,"rf":true}'

./ws.js enb '{"message":"stats", "samples":true,"rf":true ,"Initial_delay":0.7}'

./ws.js enb '{"message":"ue_get"}'

./ws.js enb '{"message":"ue_get","stats":true}'

./ws.js enb '{"message":"erab_get"}'

./ws.js enb '{"message":"qos_flow_get"}'

./ws.js enb '{"message":"cell_gain","cell_id":1,"gain":-20}'   // cell_id should be changed according to the connection status in your test. you may figure out the cell_id with cell command.

./ws.js enb '{"message":"rf"}'

./ws.js enb '{"message":"rf","tx_gain":70}'

./ws.js enb '{"message":"rf","rx_gain":50}'

./ws.js enb '{"message":"rf","rx_agc":-10}'

./ws.js enb '{"message":"rrc_ue_info_req","enb_ue_id":24,"req_mask":0}'  // enb_ue_id should be changed according to the connection status in your test. you may figure out the enb_ue_id  with ue command.

./ws.js enb '{"message":"rrc_ue_cap_enquiry","enb_ue_id":27}'  // enb_ue_id should be changed according to the connection status in your test. you may figure out the enb_ue_id  with ue command.

./ws.js enb '{"message":"rrc_cnx_release","enb_ue_id":27}'  // enb_ue_id should be changed according to the connection status in your test. you may figure out the enb_ue_id  with ue command.

./ws.js enb '{"message":"dci_bwp_switch","enb_ue_id":45,"dl_bwp_id":0,"ul_bwp_id":0}'  // enb_ue_id should be changed according to the connection status in your test. you may figure out the enb_ue_id  with ue command.

./ws.js enb '{"message":"x2"}'

./ws.js enb '{"message":"s1"}'

./ws.js enb '{"message":"s1connect"}'

./ws.js enb '{"message":"s1disconnect"}'

./ws.js enb '{"message":"ng"}'

./ws.js enb '{"message":"ngconnect"}'

./ws.js enb '{"message":"ngdisconnect"}'

./ws.js enb '{"message":"sib_set","cells":{"1":{"sib1":{"p_max":20}}}}'  

./ws.js enb '{"message":"page_ue","cell_id":[1],"type":"normal","cn_domain":"ps","imsi":"001010123456789"}'

./ws.js enb '{"message":"rrc_cnx_reconf","enb_ue_id":1,"dl_bwp_id":1,"ul_bwp_id":1}'// enb_ue_id should be changed according to the connection status in your test. you may figure out the enb_ue_id  with ue command.

./ws.js enb '{"message":"dci_bwp_switch","enb_ue_id":1,"ul_bwp_id":1}'// enb_ue_id should be changed according to the connection status in your test. you may figure out the enb_ue_id  with ue command.

./ws.js enb '{"message":"dci_bwp_switch","enb_ue_id":1,"dl_bwp_id":1}'  // enb_ue_id should be changed according to the connection status in your test. you may figure out the enb_ue_id  with ue command.

./ws.js enb '{"message":"trx_iq_dump", "duration":5000 , "rx_filename":"\tmp\rx.bin", "tx_filename":"\tmp\tx.bin"}''

./ws.js enb '{"message":"pdcch_order_prach", "enb_ue_id":1 }'// enb_ue_id should be changed according to the connection status in your test. you may figure out the enb_ue_id  with ue command.

./ws.js enb '{"message": "config_set","cells": {"1": {"rrc_procedure_filter":{"rrc_connection_request":"reject"}}}}'

./ws.js enb '{"message":"config_set","cells":{"1":{"pdsch_mcs":4}}}'

./ws.js enb '{"message":"config_set","cells":{"1":{"force_dl_schedule":true}}}'

./ws.js enb '{"message":"config_set","cells":{"1":{"pdsch_fixed_rb_alloc":true,"pdsch_fixed_rb_start":0,"pdsch_fixed_l_crb":20}}}'

./ws.js enb '{"message":"config_set","cells":{"1":{"inactivity_timer":60000}}}'

 

 

enb Remote API for cell specific configurations

 

One of the most complicated and sometimes confusing Remote API format would be for those configurations that are applied for a specific cell. It would be a good idea of understanding the general structure of Remote API command for this type of configuration. The general structure of the remote API command for this category is as shown below.

 

There are a lot of configurations that belong to this category. In the  lteenb.pdf -  10. Remote API , the parameters indicated as below belong to this category meaning you need to use the same format shown above.

 

There are other types of message that uses the same RemoteAPI command structure. It is 'cells' parameters for sib_set message as shown below.

 

In the  lteenb.pdf -  10. Remote API , the parameters indicated as below belong to this category meaning you need to use the same format shown above.

 

Followings are the list of other examples that belong to this category. (NOTE : If you are just interested in getting a proper syntax, you may just copy the example here and change cell id and configuration values as per your need. If you want to see the final outcome of the execution of these commands in real test, click on Related Tutorial).

Remote API Command	Related Tutorial
./ws.js enb '{"message":"config_set","cells":{"1":{"inactivity_timer":6000}}}'	RemoteAPI_PhyMAC
./ws.js enb '{"message":"config_set","cells":{"1":{"pdsch_mcs":2}}}'	RemoteAPI_PhyMAC
./ws.js enb '{"message":"config_set","cells":{"1":{"force_dl_schedule":true}}}'	RemoteAPI_PhyMAC
./ws.js enb '{"message":"config_set","cells":{"1":{"pdsch_fixed_rb_alloc":true,"pdsch_fixed_rb_start":0,"pdsch_fixed_rb_l_crb":20}}}'	RemoteAPI_PhyMAC
./ws.js enb '{"message":"config_set","cells":{"1":{"pusch_mcs":2}}}'	RemoteAPI_PhyMAC
./ws.js enb '{"message":"config_set","cells":{"1":{"force_full_bsr":true}}}'	RemoteAPI_PhyMAC
./ws.js enb '{"message":"sib_set","cells":{"1":{"sib1":{"p_max":20}}}}'	RemoteAPI SIB
./ws.js enb '{"message":"sib_set","cells":{"1":{"sib3":{ "type": "hex", "payload" : "000c16043f95aa0007ae"}}}}'	RemoteAPI SIB

 

 

 

mme Remote API

 

A challenge to use Remote API is that it is difficult to figure out accurate syntax of the each API just from the document. Main objective of this tutorial is to make a list of examples that is tested working. You may just copy and past of these examples for your needs but be careful about the parameter value and change those values as per the call status which your DUT is in (e.g, UE ID). This list will keep updated as I try more. So refer to the latest version of this tutorial to get more examples.

NOTE :  For Windows users, you may get errors if you just copy and paste the command as below. Check out JSON String issue on Windows to workaround the problem.

NOTE :  Refer to ltemme.pdf - 6. Remote API

./ws.js mme '{"message": "ue_get"}'

./ws.js mme '{"message": "ue_detach","imsi":"001010123456789","imei":"869057056356291"}'

./ws.js mme '{"message": "ue_deactivate_bearer","imsi":"001010123456789","imei":"869057056356291", "erab_id":5}'  

./ws.js ims '{"message": "users_get", "registered_only":1}'

./ws.js ims '{"message": "mt_cs_paging", "imsi":"001010123456789"}'

./ws.js mme '{"message": "ue_get"}'

./ws.js mme '{"message": "config_set","attach_reject_filter":{"*": 0,"001010123456789": 1}, "attach_reject_error": 14}'

./ws.js mme '{"message": "config_set","t3512":30}'

./ws.js mme '{"message": "config_set","5gmm_procedure_filter":{"registration_mobility_periodic":"reject"},"registration_mobility_periodic_error":22}'

./ws.js mme '{"message": "ue_modify_bearer","imsi":"001010123456789","imei":"869057056356291","erab_id":5,"qos":  

        {

          "qci": 6,

          "priority_level": 15,

          "pre_emption_capability": "shall_not_trigger_pre_emption",

          "pre_emption_vulnerability": "not_pre_emptable"

        }

       }'

./ws.js mme '{"message": "config_set", "pdn_list":[{"apn":"ims","esm_procedure_filter":{"pdn_connectivity":"reject"}}],"pdn_connect_reject_error":27}'

./ws.js mme '{"message": "config_set", "pdn_list":[{"apn":"ims","esm_procedure_filter":{"pdn_connectivity":"treat"}}]}'

 

 

UEsim Remote API

 

A challenge to use Remote API is that it is difficult to figure out accurate syntax of the each API just from the document. Main objective of this tutorial is to make a list of examples that is tested working. You may just copy and past of these examples for your needs but be careful about the parameter value and change those values as per the call status which your DUT is in (e.g, UE ID). This list will keep updated as I try more. So refer to the latest version of this tutorial to get more examples.

NOTE :  For Windows users, you may get errors if you just copy and paste the command as below. Check out JSON String issue on Windows to workaround the problem.

NOTE : Refer to lteue.pdf - 7. Remote API

NOTE : Following two example requires proper mme.cfg settings on Callbox and it is also assumed that default bearer with id = 5 is already established

./ws.js ue '{"message":"ue_activate_dedicated_bearer","ue_id":1,"def_bearer_id":5,"qci":4,"filters":[{ "direction":"both","id":1,"precedence":1,"components":[{"ipv4_remote_addr": "192.168.2.1","type_of_service":"ipv4","mask":"255.255.255.0"}]}]}'

 ./ws.js ue '{"message":"ue_activate_dedicated_bearer","ue_id":1,"def_bearer_id":5,"qci":4,"gbr": {"maximum_bitrate_dl": 49000, "maximum_bitrate_ul":49000,"guaranteed_bitrate_dl":49000,"guaranteed_bitrate_ul":49000},"filters":[{ "direction":"both","id":1,"precedence":1,"components":[{"ipv4_remote_addr": "192.168.2.2","type_of_service":"ipv4","mask":"255.255.255.0"}]}]}'

 

 

Application Examples

 

Followings are examples of Remote API that are used in various other tutorials in tech-academy.

• SIB Change
• Modify EPS Bearer
• BWP Switch with RRC Trigger
• BWP Switch with DCI 0_1 Trigger
• BWP Switch with DCI 1_1 Trigger
• IQ Capture
• PDCCH Order
• Attach Reject with the cause # 14 with Remote API (LTE)
• Reject Periodic Registration with the cause # 22 with Remote API (NR SA)
• Changing SIB parameters
• Changing PHY/MAC Configuration

 

 

Troubleshooting Tips

 

Syntax Error : Unexpected Token

Very often ( for example, when you copy and paste Remote API command from the document into your command prompt or when you made some typos), you may see a syntax error : Unexpected Token. In this case, you can figure out the exact position of the character that caused the problem from the error message as shown below.  

NOTE : when you copy and paste the command from a document, it may cause this kind of error because some quotation mark (' or ") would not be properly pasted. In this case, retype these quotation mark.

 

JSON String issue on Windows 

You may get errors when you run the same command on Windows PC. It seems this is due to the way how Windows command line program handles JSON string. Even on the same Windows operating system, you would need different solution for different type of command line window (e.g, regular command line window vs powershell window).  Following is the example done on Windows 11.

If you run the command as you do on Linux, you may get errors as shown below.

If you are running the command from Powershell, changing the string format as shown below may fix the problem. ( node ws.js 192.168.100.17:9001 '{\"message\":\"config_get\"}' )

If you are running the command on regular command line window, changing the string format as shown below may fix the problem. ( node ws.js 192.168.100.17:9001"{\"message\":\"config_get\"}")