Amarisoft

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

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.

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.

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

RemoteAPI NodeJ CheckUp 02

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).

RemoteAPI NodeJ CheckUp 03

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

RemoteAPI NodeJ CheckUp 04

Press Ctrl+D to get out of node program

What if nodeJ is not installed

If Node.js is not installed on the PC (Callbox), the websocket example cannot run because the required Node.js runtime and npm package manager are missing. To install them, first make sure the PC is connected to the internet, because the installation process needs to download the necessary packages from the configured repositories.

Run the command "dnf install nodejs npm" to install Node.js and npm:

After Node.js and npm are installed, run the next command "npm install nodejs-websocket" to install the nodejs-websocket package, which is required by the websocket application:

Once these steps are completed, the PC will be ready to run Node.js-based websocket scripts.

RemoteAPI NodeJ Install 01

RemoteAPI NodeJ Install 02

Finding ws.js

The location of ws.js is a little bit different depending on release of the installlation package.  If you are using the latest release, you will find in following directory.

The ws.js for enb is located in /root/enb directory as shown below

[root@CBC-2023010100 doc]# cd /root/enb

[root@CBC-2023010100 enb]# ll

total 34800

drwxr-xr-x  6   33 tape    16384 Mar  9 12:29 config

drwxr-xr-x  3 root root     4096 Feb 28 10:21 doc

-rwxr-xr-x  1 root root  5666328 Feb 28 10:21 libcrypto.so.3

-rwxr-xr-x  1   33 tape    75656 Feb 27 12:28 libnopoll.so

-rwxr-xr-x  1   33 tape    55608 Feb 27 12:28 libnuma.so

lrwxrwxrwx  1 root root       23 Feb 28 10:21 libsdr.so -> /root/trx_sdr/libsdr.so

-rwxr-xr-x  1 root root  1039632 Feb 28 10:21 libssl.so.3

-rw-r--r--  1   33 tape   256335 Feb 27 12:29 license.pdf

-rw-r--r--  1   33 tape    19506 Feb 27 12:29 license.txt

-rwxr-xr-x  1   33 tape    88352 Feb 27 12:28 lteenb

-rwxr-xr-x  1   33 tape 14226560 Feb 27 12:29 lteenb-avx2

-rwxr-xr-x  1   33 tape 14078240 Feb 28 10:17 lteenb-sse4_1

-rwxr-xr-x  1   33 tape    15659 Feb 27 12:29 lte_init.sh

drwxrwxr-x 10 user user     4096 Apr  9  2020 node_modules

-rwxr-xr-x  1   33 tape    18384 Feb 27 12:28 trx_dummy.so

-rwxr-xr-x  1 root root     8000 Feb 28 10:21 trx-iq-dump.js

lrwxrwxrwx  1 root root       24 Feb 28 10:21 trx_sdr.so -> /root/trx_sdr/trx_sdr.so

-rwxr-xr-x  1   33 tape    22784 Feb 27 12:29 vrb_dpdk.so

-rwxr-xr-x  1 root root    15807 Feb 28 10:21ws.js

The ws.js for mme and ims is located in /root/enb directory as shown below

[root@CBC-2023010100 enb]# cd /root/mme

[root@CBC-2023010100 mme]# ll

total 18860

drwxr-xr-x  3   33 tape   12288 Feb 28 10:21 config

drwxr-xr-x  3 root root    4096 Feb 28 10:21 doc

-rwxr-xr-x  1 root root 5666328 Feb 28 10:21 libcrypto.so.3

-rwxr-xr-x  1 root root  190512 Feb 28 10:21 libnghttp2.so.14

-rwxr-xr-x  1   33 tape   75656 Feb 27 12:30 libnopoll.so

-rwxr-xr-x  1   33 tape   55608 Feb 27 12:30 libnuma.so

-rwxr-xr-x  1   33 tape   73152 Feb 27 12:30 libosip2.so

-rwxr-xr-x  1   33 tape  163976 Feb 27 12:30 libosipparser2.so

-rwxr-xr-x  1 root root 1039632 Feb 28 10:21 libssl.so.3

-rw-r--r--  1   33 tape  256335 Feb 27 12:30 license.pdf

-rw-r--r--  1   33 tape   19506 Feb 27 12:30 license.txt

-rwxr-xr-x  1   33 tape 1321504 Feb 28 10:17 lteims

-rwxr-xr-x  1   33 tape    7914 Feb 27 12:30 lte_init.sh

-rwxr-xr-x  1   33 tape 9829120 Feb 28 10:17 ltemme

-rwxr-xr-x  1   33 tape  555392 Feb 27 12:30 ltesim_server

drwxrwxr-x 10 user user    4096 Apr  9  2020 node_modules

-rwxr-xr-x  1 root root   15807 Feb 28 10:21ws.js

 

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 example, if you want to try ws.js for enb. run a simple command as follows and see if you get the proper result.  This command is executed with ws.js for the enb target. (NOTE : the Amarisoft software must already be running before this command is issued. Otherwise, the connection test would fail because there would be no active service listening for the request..

[root@CBC-2023010100 enb] cd /root/enb

[root@CBC-2023010100 enb]# ./ws.js enb '{"message":"config_get"}'

WebSocket remote API tool version 2026-02-27, Copyright (C) 2012-2026 Amarisoft

[0.004] ### Connected to 127.0.0.1:9001

[0.004] ### Ready: name=ENB, type=ENB, version=2026-02-27, product=CBC

[0.024] <== Send message config_get id#1

[0.026] ==> Message received

{

    "message": "config_get",

    "message_id": "id#1",

    "version": "2026-02-27",

    "type": "ENB",

    "name": "ENB",

    "logs": {

        "layers": {

            "PHY": {

                "level": "error",

                "max_size": 0,

                "key": false,

                "crypto": false,

                "payload": false,

                "signal": false,

                "cch": false,

                "rep": false,

                "dci_size": false,

                "csi": false,

                "cell_meas": false,

                "ntn": false,

                "icic": false

            },

  ....

This command is executed with ws.js for the mme or ims target. (NOTE : the Amarisoft software must already be running before this command is issued. Otherwise, the connection test would fail because there would be no active service listening for the request..

[root@CBC-2023010100 enb]# cd /root/mme

[root@CBC-2023010100 mme]# ./ws.js mme '{"message":"config_get"}'

WebSocket remote API tool version 2026-02-27, Copyright (C) 2012-2026 Amarisoft

[0.005] ### Connected to 127.0.0.1:9000

[0.006] ### Ready: name=MME, type=MME, version=2026-02-27, product=CBC

[0.025] <== Send message config_get id#1

[0.036] ==> Message received

{

    "message": "config_get",

    "message_id": "id#1",

    "version": "2026-02-27",

    "type": "MME",

    "name": "MME",

    "logs": {

        "layers": {

            "NAS": {

                "level": "debug",

                "max_size": 32,

                "key": false,

                "crypto": false,

                "payload": false,

                "plmn": false

            },

            "IP": {

                "level": "debug",

                "max_size": 32,

                "key": false,

                "crypto": false,

                "payload": false

            },

            "S1AP": {

                "level": "debug",

                "max_size": 32,

                "key": false,

                "crypto": false,

                "payload": false

            },

 

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.

RemoteAPI ComponentIP 01

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.

RemoteAPI ComponentIP 02

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.

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.

The important field is "cells". This section tells the system that the configuration change applies to cell-specific settings rather than to the global eNB configuration. The "cells" field is structured as a dictionary where each entry represents a specific cell.

Inside the "cells" block, the value "1" represents the cell ID. This identifies which cell in the eNB configuration will receive the parameter change. If the eNB is running multiple cells, each one would appear with its own identifier such as "1", "2", "3", and so on.

Within the cell block, the parameter "inactivity_timer":600000 is the actual configuration parameter being applied. In this case, it sets the inactivity timer for the specified cell. The value 600000 represents the timer duration in milliseconds.

The bracket structure is important for understanding the hierarchy of the command. The outer JSON object contains the message type. Inside it, the "cells" object groups all cell-specific configurations. Within "cells", each cell ID has its own configuration block, and the parameters inside that block apply only to that particular cell.

After the command is sent, the terminal output shows that the WebSocket remote API tool connects to 127.0.0.1:9001, identifies the eNB instance, sends the config_set message, and receives a confirmation response. The returned JSON confirms that the request was processed successfully.

This structure is commonly used when modifying parameters that belong to the cell configuration layer, such as timers, radio parameters, scheduling options, or other cell-level settings. Understanding this nested JSON format is important because many Amarisoft Remote API commands follow the same pattern when targeting specific cells.

RemoteAPI eNB Cell Params 01

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.

This section of the document shows that many configuration parameters in the Remote API belong to the cell-specific configuration category. When a parameter falls into this category, it must be applied using the same config_set → cells → cell_id → parameter structure that was introduced earlier.

The config_set message is used to modify the current configuration of the running system. Each member inside the message is optional, meaning that only the parameters that need to be changed must be included. The API allows configuration updates without restarting the system, which is why this command is commonly used during testing or live operation.

The most important object in this section is cells. This object is used when configuration parameters must be applied individually to specific cells. Inside the cells object, each configured cell is represented as a separate object whose key is the cell ID.

A simplified structure looks like this:

"cells": {

    "1": {

        ...

    },

    "2": {

        ...

    }

}

Each cell ID becomes the key of a configuration block, and any parameters placed inside that block apply only to that specific cell.

For example:

pusch_mcs specifies the MCS used for PUSCH. It can be either a single integer or an array of 10 integers. The allowed range is from –1 to 28. This parameter can force a specific PUSCH MCS value for testing purposes. If an array is used, each entry corresponds to the MCS value applied to a particular subframe.

pusch_fixed_rb_alloc controls whether a fixed RB allocation is used for PUSCH transmission. This parameter can be either a boolean value or an array of booleans. If an array is used, its length must divide evenly into 10, and each element indicates whether a fixed RB allocation should be used for the corresponding subframe index.

The key idea is that all parameters listed under the cells section in the Remote API documentation must be configured using the same nested structure:

Understanding this hierarchy is important because many radio parameters - such as scheduling options, PUSCH configuration, timers, and other PHY/MAC settings - are defined on a per-cell basis and therefore must be configured using this format.

RemoteAPI eNB Cell Params 02

There are other types of message that uses the same RemoteAPI command structure. This example shows that the same Remote API command structure used for config_set with the cells parameter is also used by other message types. One of the most common examples is the sib_set message, which is used to modify System Information Block (SIB) parameters.

In this command, the field "message":"sib_set" indicates that the request is intended to update SIB parameters in the running eNB configuration. Instead of modifying general configuration values, this command modifies information that is broadcast by the cell to the UE.

Just like the previous examples, the command uses the cells object to specify which cell the configuration should be applied to. Inside the cells object, the key "1" represents the cell ID. This ensures that the change is applied only to that specific cell.

Within the cell configuration block, the command specifies the SIB structure that needs to be updated. In this example, the configuration targets sib1, which is the System Information Block that carries fundamental cell access parameters.

Inside the sib1 block, the parameter "p_max":20 is set. This parameter defines the maximum allowed UE transmit power for the cell, expressed in dBm. By sending this command through the Remote API, the system updates the SIB1 configuration for the specified cell.

RemoteAPI eNB Cell Params 03

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.

Following document shows which parameters in the Remote API documentation belong to the sib_set → cells configuration category. Any parameter listed under this category must follow the same cell-specific Remote API command structure explained earlier.

The sib_set message is used to modify the System Information Blocks (SIBs) that are broadcast by the cell. When these parameters are updated, the system advertises a BCCH system information modification so that UEs become aware that system information has changed.

Just like the config_set message, the sib_set command also uses the cells object to indicate that the configuration applies to a specific cell. Each configured cell must appear as a new object inside the cells structure, and the object name must correspond to the cell ID.

The structure therefore follows this hierarchy:

    sib_set --> cells --> cell_id --> sibX parameters

Within the cells object, several SIB configuration blocks can be defined. One common example is sib1, which contains key parameters related to basic cell access and system broadcast information.

Inside the sib1 configuration block, several optional parameters may appear.

cell_barred indicates whether the cell should be barred from access. This parameter can be set to true, false, or "auto". If "auto" is used, the system determines whether the cell should be barred based on the broadcast PLMN configuration. This parameter applies only to LTE or NB-IoT cells.

p_max defines the maximum transmit power allowed for a UE in the cell. This is an optional integer value and updates the broadcast P-Max value if the parameter is already present in the SIB configuration.

timers_and_constants is an optional object used to configure several radio timers and constants. This parameter is applicable only to NR cells, and its detailed structure is described separately in the documentation.

uac_barring_info controls Unified Access Control (UAC) barring information. This is also an optional object and applies only to NR cells. When this field is present in the command, the entire UAC barring configuration is replaced with the provided structure. The user must therefore ensure that the provided configuration is complete and valid. Setting info_set_list to an empty array ([]) removes the existing UAC barring configuration.

ss_pbch_block_power specifies the SS/PBCH block transmit power for NR cells. It is an optional integer with a valid range from –60 to 50 dBm, and it is used only when manual_ref_signal_power is enabled.

The document also indicates that other SIB objects such as sib2 can appear under the same hierarchy. Each SIB block contains its own parameters, but they all follow the same Remote API command structure.

The key point is that all parameters listed under sib_set → cells must use the same nested Remote API format, where the configuration is applied to a specific cell ID inside the cells object. This ensures that the updated SIB configuration is applied only to the intended cell and then broadcast to UEs through the normal system information update procedure.

RemoteAPI eNB Cell Params 04

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

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

Application Examples

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

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.  

This troubleshooting example explains a very common Remote API problem. It is a JSON syntax error. The specific error shown is SyntaxError: Unexpected token. The screenshot shows a sib_set command entered through ws.js. The command is intended to set p_max under sib1 for cell 1. But the JSON format is broken, so the tool cannot parse the message correctly. The terminal first shows that the WebSocket tool starts normally and connects successfully to 127.0.0.1:9001. So the Remote API itself is running properly. The failure happens after connection, when the command string is interpreted as JSON.

RemoteAPI TroubleshootTips UnexpectedToken 01

This tells you two important things. First, the problem is not with Amarisoft itself. The problem is with the JSON text that was typed or pasted into the command. Second, the parser tells you the exact character position where it found the problem. In this example, it says position 30. That means the invalid character is around that point in the JSON string

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.

JSON command strings may behave differently on Windows than on Linux. The main issue is not the Remote API itself, but how each Windows command shell interprets quotation marks and escape characters.

A command that works directly on Linux may fail on Windows with a JSON parsing error. Also, even within Windows, PowerShell and the regular Command Prompt may require different string formats.

The examples show that the fix is usually to adjust the quoting and escaping style to match the shell you are using. Once the JSON string is formatted correctly for that specific Windows environment, the same config_get command works normally and returns the expected response.

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

RemoteAPI TroubleshootTips Windows Error 01

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

RemoteAPI TroubleshootTips Windows Error 02

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\"}")

RemoteAPI TroubleshootTips Windows Error 03

© 2025 All rights reserved | Legal notice |