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
• Introduction
• Summary of the Tutorial
• 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 

Introduction

The Remote API is an advanced automation and remote control interface designed for seamless integration with Amarisoft's Amari Callbox and UEsim platforms. Leveraging the WebSocket protocol, the Remote API enables bidirectional, low-latency communication between test equipment and external automation clients, regardless of their programming language, provided they support WebSocket connectivity. Unlike traditional automation protocols such as GPIB/SCPI, which are prevalent in legacy test equipment, Amarisoft’s Remote API adopts a modern, JSON-based command structure that enhances flexibility and expressiveness for test automation scenarios. Architecturally, this interface operates as a lightweight, scriptable layer—commonly implemented in JavaScript—enabling users to issue commands, monitor events, and retrieve real-time information from the Callbox or UEsim. This approach is particularly significant in the context of 4G/5G network emulation, where dynamic test control, scenario customization, and real-time data acquisition are critical. By decoupling the control protocol from SCPI’s rigid command sets, Remote API empowers users to implement complex automation workflows, integrate with CI/CD pipelines, and support a broader range of use cases in both research and commercial test environments. Furthermore, while the standard release does not include a dedicated Python API wrapper, users can readily utilize or adapt sample Python code provided in this tutorial to interface with the Remote API, further broadening its accessibility across diverse development ecosystems.

• Technology Context
  • Remote API serves as a modern automation and remote control solution for Amarisoft test platforms, enabling efficient communication via WebSocket and JSON-formatted commands.
  • Replaces legacy mechanisms such as GPIB/SCPI with a more flexible, script-driven interface suitable for contemporary automation needs.
  • Supports integration with a variety of programming environments, including JavaScript and Python, facilitating cross-platform compatibility.
• Relevance and Importance
  • Essential for automating complex test sequences in 4G/5G network emulation, where traditional manual control or legacy automation protocols fall short.
  • Enables dynamic scenario management, real-time monitoring, and advanced control required by modern wireless research and development workflows.
  • Empowers users to extend automation capabilities beyond the constraints of standard command sets by leveraging the expressiveness of JSON and WebSocket communication.
• What Learners Will Gain
  • Comprehensive understanding of how to set up and utilize the Remote API with Amarisoft Callbox and UEsim products.
  • Practical skills in establishing WebSocket connections, formatting JSON commands, and processing responses for automation tasks.
  • Ability to adapt or extend sample Python code to suit custom testing and automation requirements, regardless of the programming language used.
• Prerequisite Knowledge or Skills
  • Basic familiarity with network protocols, particularly WebSocket, and general automation concepts.
  • Experience with at least one programming language that supports WebSocket communication (e.g., Python, JavaScript).
  • Understanding of Amarisoft’s Callbox or UEsim operational workflows will be beneficial for practical exercises.

Summary of the Tutorial

This tutorial provides comprehensive procedures for testing and utilizing the Amarisoft Remote API functionalities on the Callbox system, focusing on establishing the environment, verifying nodeJ (Node.js) installation, locating essential scripts, sending basic and advanced Remote API commands, and troubleshooting common issues.

• Test Setup
  • Any test setup that allows the UE to attach to the callbox can be used.
• Check if nodeJ is installed
  • Verify NodeJ (Node.js) installation by running node -v in the terminal. If the version prints, NodeJ is installed.
  • For additional verification, enter the node shell using the node command, define and invoke a simple function (like HelloWorld()), and ensure it executes correctly.
  • Exit the node shell with Ctrl+D.
• NodeJ Installation (if not installed)
  • If NodeJ is not present, connect the PC to the internet and install NodeJ using the appropriate installation commands shown in the tutorial.
• Finding ws.js
  • The ws.js script's location may vary by software release. Older versions store it in /root/mme/doc, while newer releases may use /root/enb, /root/mme, or /root/ots.
  • If unsure, use the find command to locate ws.js on the filesystem.
• Checking ws.js
  • To test if RemoteAPI functions properly, send a simple command using ws.js (e.g., ./ws.js enb '{"message":"config_get"}') and verify that a valid response is received.
  • For this test, ensure the LTE service is running; UE attachment is not required.
• Determining IP and Port for Components
  • Component names can typically be used in Remote API commands. If explicit IP:port is needed, check the ws.js file or configuration files (e.g., enb.cfg, mme.cfg) for the com_addr parameter.
• enb Remote API Procedures
  • A series of tested Remote API command examples are provided for controlling and querying the eNB/gNB component via ws.js.
  • Commands cover configuration retrieval and changes, stats collection, UE and bearer management, cell gain adjustments, RF settings, RRC procedures, DCI/BWP switching, paging, SIB parameter changes, and more.
  • Important parameters such as enb_ue_id and cell_id must be adapted to the current test context (e.g., actual UE IDs or cell IDs in use).
  • For cell-specific configurations, commands must use the correct structure under the cells parameter. Examples detail how to set timers, MCS, scheduling, SIB content, and other cell-level settings.
  • A table of additional tested cell-specific command examples is provided, with references to related tutorials for further detail.
• mme Remote API Procedures
  • Tested examples include commands for UE information retrieval, detaching UEs, deactivating bearers, IMS user management, paging, bearer modification, attach/registration rejection, and PDN configuration manipulation.
  • Some commands include JSON sub-structures for specifying QoS or procedure filters.
  • Windows users are advised to check for JSON string handling issues and use workarounds as described.
• UEsim Remote API Procedures
  • Examples illustrate activation of dedicated bearers on the simulated UE, including specifying QoS parameters and packet filters.
  • Prerequisite: Proper mme.cfg configuration and pre-established default bearer with ID 5.
• Application Examples
  • The tutorial references additional application examples covering SIB changes, EPS bearer modification, BWP switching, IQ captures, PDCCH orders, and various NAS rejection scenarios. These can be accessed in related tutorials for more in-depth test cases.
• Troubleshooting Tips
  • Syntax errors, especially "Unexpected Token," often result from incorrect quotation marks when copying commands. Retyping the quotes may resolve the issue.
  • On Windows, JSON string handling may vary between command line and PowerShell. Adjust the command format as shown in the tutorial to avoid errors.

Throughout the tutorial, users are reminded to carefully adjust context-dependent parameters (e.g., enb_ue_id, cell_id, imsi) to match their test scenario and to refer to official Amarisoft documentation for detailed command syntax and parameter descriptions.

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"}}]}'

./ws.js ims '{"message":"sms","impu":"0600000000","binary_hex":"0741524745543a20506c"}'  

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
• IQ Dump
• PDCCH Order
• Attach Reject with the cause # 14
• Reject Periodic Registration with the cause # 22
• Reject Periodic Registration with the cause # 22 and t3512
• Attach Reject with the cause # 20 and then Attach Accept(removing reject)
• Initial Registration Reject with the cause # 22
• Attach Reject/TAU Reject with the cause # 22 - T3412, T3402
• 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\"}")